Skip to content
Browse files
Add taxonomy docs and fix post-list docs
Signed-off-by: Chris Warrick <>
  • Loading branch information
Kwpolska committed Aug 31, 2016
1 parent 263f1bd commit e3e3ecc48d34b2ef6c6defeeb09f0814233b174d
Showing 2 changed files with 76 additions and 4 deletions.
@@ -1,3 +1,3 @@
"last_deploy": "2016-08-30T12:56:15.385697"
"last_deploy": "2016-08-31T07:30:21.032669"
@@ -384,7 +384,8 @@ previewimage
but should less than 1 MB and be larger than 300x300 (ideally 600x600).

Section for the post (overrides section inferred from path)
Section for the post (instead of inferring from output path; requires

Change the template used to render this page/post specific page. That
@@ -743,6 +744,77 @@ 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).

Post taxonomy

There are three taxonomy systems in Nikola, or three ways to organize posts. Those are:

* tags
* categories
* sections

Tags and categories are visible on the *Tags and Categories* page, by default available at ``/categories/``. Each tag/category/section has an index page and feeds.


Tags are the smallest and most basic of the taxonomy items. A post can have multiple tags, specified using the ``tags`` metadata entry (comma-separated). You should provide many tags to help your readers, and perhaps search engines, find content on your site.

Please note that tags are case-sensitive and that you cannot have two tags that differ only in case/punctuation (eg. using ``nikola`` in one post and ``Nikola`` in another will lead to a crash):

.. code:: text

ERROR: Nikola: You have tags that are too similar: Nikola and nikola
ERROR: Nikola: Tag Nikola is used in: posts/second-post.rst
ERROR: Nikola: Tag nikola is used in: posts/1.rst

Nikola uses some tags to mark a post as “special” — those are ``draft``, ``private``, ``mathjax`` (for math support).

You can also generate a tag cloud with the `tx3_tag_cloud <>`_ plugin.


The next unit for organizing your content are categories. A post can have only one category, specified with the ``category`` meta tag. Those are *deprecated* and replaced by sections. They are displayed alongside tags. You can have categories and tags with the same name (categories’ RSS and HTML files are prefixed with ``cat_`` by default).


Sections are the newest feature for taxonomy, and are not supported in themes by default. There are two ways to assign a section to a post:

* through the directory structure (first directory is the section name, eg. ``/code/my-project/`` is in the `code` category) — your POSTS should have those directories as the second element, eg.

.. code:: python

('posts/code/*.rst', 'code', 'posts'),

* through the ``section`` meta field (requires ``POSTS_SECTION_FROM_META`` setting; recommended especially for existing sites which should not change the directory hierarchy)

Sections are meant to be used to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, you should ideally have less than 10 sections (though it depends on what your blog needs; there is no hard limit).

With sections, you can also use come custom styling — if you install ``husl``, you can use ``post.section_color()`` from within templates to get a distinct color for the section of a post, which you can then use in some inline CSS for the section name.

You can find some examples and more information in the `original announcement

Configuring tags, categories and sections

There are multiple configuration variables dedicated to each of the three taxonomies. You can set:

* ``TAG_PATH``, ``TAGS_INDEX_PATH``, ``CATEGORY_PATH``, ``CATEGORY_PREFIX`` to configure paths used for tags and categories
* ``POST_SECTION_NAME``, ``POST_SECTION_TITLE`, `TAG_PAGES_TITLES``, ``CATEGORY_PAGES_TITLES`` to set friendly section names and titles for index pages
* ``POST_SECTION_COLORS`` to customize colors for each section
* ``CATEGORY_ALLOW_HIERARCHIES`` and ``CATEGORY_OUTPUT_FLAT_HIERARCHIES`` to allow hierarchical categories
* ``TAG_PAGES_ARE_INDEXES`` and ``CATEGORY_PAGES_ARE_INDEXES`` to display full-size indexes instead of simple post lists
* ``WRITE_TAG_CLOUDS`` to enable/disable generating tag cloud files
* ``HIDDEN_TAGS``. ``HIDDEN_CATEGORIES`` to make some tags/categories invisible in lists
* ``POSTS_SECTION_FROM_META`` to use ``.. section:`` in posts instead of inferring paths from paths

Creating a Page

@@ -2136,9 +2208,9 @@ with the tag ``nikola``:

Using shortcode syntax (for other compilers):

.. code:: markdown
.. code:: text

{{% post-list stop=5 %}}{{% /post-list %}}
{{% raw %}}{{% post-list stop=5 %}}{{% /post-list %}}{{% /raw %}}

The following options are recognized:

0 comments on commit e3e3ecc

Please sign in to comment.