Fix #1829 -- document static indexes

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jun 21, 2015 · cba97c8 · felixfontein · Jun 21, 2015 · Kwpolska
1 parent d705b32
commit cba97c8
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 1 deletion.
diff --git a/docs/manual.txt b/docs/manual.txt
@@ -877,6 +877,48 @@ Using Pandoc for reStructuredText, Markdown and other input formats that have a
 standalone Nikola plugin is **not recommended** as it disables plugins and
 extensions that are usually provided by Nikola.
 
+Indexes
+~~~~~~~
+
+All your posts that are not drafts, private or dated in the future, will be
+shown in indexes.
+
+Settings
+````````
+
+Indexes are put in the ``INDEX_PATH`` directory, which defaults to an empty
+string (site root).  The “main” index is ``index.html``, and all the further
+indexes are ``index-*.html``, respectively.
+
+By default, 10 posts are displayed on an index page.  This can be changed with
+``INDEX_DISPLAY_POST_COUNT``.  Indexes can show full posts or just the teasers,
+as controlled by the ``INDEX_TEASERS`` setting (defaults to ``False``).
+
+Titles of the pages can be controlled by using ``INDEXES_TITLES``,
+``INDEXES_PAGES`` and ``INDEXES_PAGES_MAIN`` settings.
+
+Categories and tags use simple lists by default that show only titles and
+dates; however, you can switch them to full indexes by using
+``CATEGORY_PAGES_ARE_INDEXES`` and ``TAG_PAGES_ARE_INDEXES``, respectively.
+
+Static indexes
+``````````````
+
+Nikola uses *static indexes* by default.  This means that ``index-1.html`` has
+the latest posts, and the newest posts are in ``index-N.html``, where ``N`` is
+the highest number.  Only the page with the highest number and the main page
+(``index-N.html`` and ``index.html``) are rebuilt (the others remain
+unchanged).  The page that appears when you click *Older posts* on the index
+page, ``index-N.html``, might contain **less than 10 posts** if there are not
+enough posts to fill up all pages.
+
+This can be disabled by setting ``INDEXES_STATIC`` to ``False``.  In that mode,
+``index-1.html`` contains all the newest posts and will always contain 10 posts
+(unless you have less than 20).  The last page, ``index-N.html``, contains the
+oldest posts, and might contain less than 10 posts.  This is how many blog
+engines and CMSes behave.  Note that this will lead to rebuilding all index
+pages, which might be a problem for larger blogs (with a lot of index pages).
+
 Creating a Page
 ---------------
 

diff --git a/nikola/conf.py.in b/nikola/conf.py.in
@@ -477,7 +477,7 @@ IMAGE_FOLDERS = {'images': 'images'}
 # INDEXES_STATIC = True
 #
 # (translatable) If PRETTY_URLS is set to True, this setting will be used to create
-# more pretty URLs for index pages, such as page/2/index.html instead of index-2.html.
+# prettier URLs for index pages, such as page/2/index.html instead of index-2.html.
 # Valid values for this settings are:
 #   * False,
 #   * a list or tuple, specifying the path to be generated,