Skip to content
Permalink
Browse files
Rename to CATEGORY_DESTPATH_* and update docs
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed May 2, 2018
1 parent cc6fac6 commit 90bbc98dbc6e14a4291ee59a7a58ddd7dbdee34b
Showing with 37 additions and 60 deletions.
  1. +4 −0 CHANGES.txt
  2. +12 −41 docs/manual.rst
  3. +6 −5 nikola/conf.py.in
  4. +9 −9 nikola/nikola.py
  5. +6 −5 nikola/post.py
@@ -15,10 +15,14 @@ Important compatibility changes
* RSS feeds might have changed their places due to ``RSS_PATH``
behavior changes (you may need to change ``RSS_PATH``,
``RSS_FILENAME_BASE``)
* Sections are replaced by categories (Issue #2833)

Features
--------

* Add ``CATEGORY_DESTPATH_AS_DEFAULT``, ``CATEGORY_DESTPATH_TRIM_PREFIX``,
``CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY`` settings, as part of
replacing sections with categories (Issue #2833)
* Tags ``draft``, ``private`` and ``mathjax`` are no longer treated
special if ``USE_TAG_METADATA`` is set to ``False`` (default for
new sites) (Issue #2761)
@@ -380,10 +380,6 @@ previewimage

Note that the default themes do not display this image.

section
Section for the post (instead of inferring from output path; requires
``POSTS_SECTION_FROM_META`` setting)

template
Change the template used to render this page/post specific page. That
template needs to either be part of the theme, or be placed in a
@@ -953,13 +949,7 @@ lead to rebuilding all index pages, which might be a problem for larger blogs
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.
There are two taxonomy systems in Nikola, or two ways to organize posts. Those are tags and categories. They are visible on the *Tags and Categories* page, by default available at ``/categories/``. Each tag/category has an index page and feeds.

Tags
````
@@ -979,44 +969,29 @@ You can also generate a tag cloud with the `tx3_tag_cloud <https://plugins.getni
Categories
``````````

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
````````

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:
The next unit for organizing your content are categories. A post can have only one category, specified with the ``category`` meta tag. 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).

* 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.
Categories are handy to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, the list of categories should be shorter.

.. code:: python
Nikola v7 used to support a third taxonomy, called sections. Those have been removed, but all the functionality can be recreated by using the ``CATEGORY_DESTPATH`` settings.

POSTS = (
('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 some 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
<https://getnikola.com/blog/new-feature-in-nikola-sections.html>`_

Configuring tags, categories and sections
`````````````````````````````````````````
Configuring tags and categories
```````````````````````````````

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_TITLES`` to set friendly section names and titles for index pages
* ``POST_SECTION_DESCRIPTIONS``, `TAG_PAGES_DESCRIPTIONS``, ``CATEGORY_DESCRIPTIONS`` to set descriptions for each of the items
* ``POST_SECTION_COLORS`` to customize colors for each section
* `TAG_PAGES_TITLES``, ``CATEGORY_TITLES`` to set titles and descriptions for index pages
* ``TAG_PAGES_DESCRIPTIONS``, ``CATEGORY_DESCRIPTIONS`` to set descriptions for each of the items
* ``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
* ``CATEGORY_DESTPATH_AS_DEFAULT`` to use the destination path as the category if none is specified in the post
* ``CATEGORY_DESTPATH_TRIM_PREFIX`` to trim the prefix that comes from ``POSTS`` for the destination path
* ``CATEGORY_DESTPATH_FIRST_DIRECTORY`` to only use the first directory name for the defaulted category
* ``CATEGORY_DESTPATH_NAMES`` to specify friendly names for defaulted categories

What if I don’t want a blog?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2719,10 +2694,6 @@ The following options are recognized:
Filter posts to show only posts having one of the ``categories``.
Defaults to None.

* ``sections`` : string [, string...]
Filter posts to show only posts having one of the ``sections``.
Defaults to None.

* ``slugs`` : string [, string...]
Filter posts to show only posts having at least one of the ``slugs``.
Defaults to None.
@@ -368,20 +368,21 @@ HIDDEN_CATEGORIES = []
# CATEGORY_TRANSLATIONS_ADD_DEFAULTS = True

# If no category is specified in a post, the destination path of the post
# can be used in its place. This replaces the
# CATEGORY_PATH_AS_DEFAULT = False
# can be used in its place. This replaces the sections feature. Using
# category hierarchies is recommended.
# CATEGORY_DESTPATH_AS_DEFAULT = False

# If True, the prefix will be trimmed from the category name, eg. if the
# POSTS destination is "foo/bar", and the path is "foo/bar/baz/quux",
# the category will be "baz/quux" (or "baz" if only the first directory is considered).
# Note that prefixes coming from translations are always ignored.
# CATEGORY_PATH_TRIM_PREFIX = False
# CATEGORY_DESTPATH_TRIM_PREFIX = False

# If True, only the first directory of a path will be used.
# CATEGORY_PATH_FIRST_DIRECTORY_ONLY = True
# CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY = True

# Map paths to prettier category names.
# CATEGORY_PATH_NAMES = {
# CATEGORY_DESTPATH_NAMES = {
# DEFAULT_LANG: {
# 'webdev': 'Web Development',
# 'random': 'Odds and Ends',
@@ -428,10 +428,10 @@ def __init__(self, **config):
'CATEGORY_PREFIX': 'cat_',
'CATEGORY_ALLOW_HIERARCHIES': False,
'CATEGORY_OUTPUT_FLAT_HIERARCHY': False,
'CATEGORY_PATH_AS_DEFAULT': False,
'CATEGORY_PATH_TRIM_PREFIX': False,
'CATEGORY_PATH_FIRST_DIRECTORY_ONLY': False,
'CATEGORY_PATH_NAMES': {},
'CATEGORY_DESTPATH_AS_DEFAULT': False,
'CATEGORY_DESTPATH_TRIM_PREFIX': False,
'CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY': False,
'CATEGORY_DESTPATH_NAMES': {},
'CATEGORY_TRANSLATIONS': [],
'CATEGORY_TRANSLATIONS_ADD_DEFAULTS': False,
'CODE_COLOR_SCHEME': 'default',
@@ -646,7 +646,7 @@ def __init__(self, **config):
'INDEX_READ_MORE_LINK',
'FEED_READ_MORE_LINK',
'INDEXES_TITLE',
'CATEGORY_PATH_NAMES',
'CATEGORY_DESTPATH_NAMES',
'INDEXES_PAGES',
'INDEXES_PRETTY_PAGE_URL',
# PATH options (Issue #1914)
@@ -747,13 +747,13 @@ def __init__(self, **config):
self.config[section_config].update(self.config[cat_config])
self.config[cat_config] = self.config[section_config]

self.config['CATEGORY_PATH_NAMES'] = self.config.get('POSTS_SECTION_NAME', {})
self.config['CATEGORY_DESTPATH_NAMES'] = self.config.get('POSTS_SECTION_NAME', {})

if self.config.get('POSTS_SECTION_FROM_META') is False:
utils.LOGGER.info("Setting CATEGORY_PATH_AS_DEFAULT = True")
self.config['CATEGORY_PATH_AS_DEFAULT'] = True
utils.LOGGER.info("Setting CATEGORY_DESTPATH_AS_DEFAULT = True")
self.config['CATEGORY_DESTPATH_AS_DEFAULT'] = True
else:
self.config['CATEGORY_PATH_AS_DEFAULT'] = False
self.config['CATEGORY_DESTPATH_AS_DEFAULT'] = False

# Handle CONTENT_FOOTER and RSS_COPYRIGHT* properly.
# We provide the arguments to format in CONTENT_FOOTER_FORMATS and RSS_COPYRIGHT_FORMATS.
@@ -247,14 +247,15 @@ def __init__(
meta['category'] = meta['section']
LOGGER.notice("Post {0} uses 'section' metadata, setting its value to 'category'".format(source_path))

# Handle CATEGORY_PATH_AS_DEFAULT
if 'category' not in meta and self.config['CATEGORY_PATH_AS_DEFAULT']:
if self.config['CATEGORY_PATH_TRIM_PREFIX']:
# Handle CATEGORY_DESTPATH_AS_DEFAULT
if 'category' not in meta and self.config['CATEGORY_DESTPATH_AS_DEFAULT']:
if self.config['CATEGORY_DESTPATH_TRIM_PREFIX']:
category = self.folder_relative
else:
category = self.folders[lang]
if self.config['CATEGORY_PATH_FIRST_DIRECTORY_ONLY']:
category = category.split(os.sep)[0] # TODO test on Windows
category.replace(os.sep, '/') # TODO: does Windows need this?
if self.config['CATEGORY_DESTPATH_FIRST_DIRECTORY_ONLY']:
category = category.split('/')[0]
meta['category'] = category

self.publish_later = False if self.current_time is None else self.date >= self.current_time

0 comments on commit 90bbc98

Please sign in to comment.