Ctrl.blog

I’ve been reorganizing and redesigning this site over the course of this week, and ended up adding a neat new feature to Nikola in the process: sections. Sections allow you to separate posts into collections and let you style each section’s posts separately.

Sections are like newspaper sections that let you group related content together in a collection. Every post from a section appear under a common name, folder/address, and optionally use distinct styling.

They also have their own landing pages containing an index with all their posts and their own syndication feed. With sections and post collections, you can diversify your Nikola blog by writing on different topics all on the same website. Readers who are only interested in one subsection of the content you publish can subscribe to the feed of the section or sections that interest them the most.

In Nikola, sections are normally built automatically based on the output folders specified in the POSTS option. Each output folder is a new section. The index pages and feeds for each section will be output in the same directory as the posts. Alternatively, sections can be assigned using a section property in each post’s metadata. Note that this will not change the output folder or address of a post and thus lose some of the uniformity you get with having posts include their section name as part of their address.

The following configuration example demonstrates how three sections on different topics are created. The first argument is the source path to where the posts are stored, the second argument is the output folder and section name, and the third argument is the template to use for each section. Posts can use the same template, but you may want to customize the template for each section with bigger hero images on your food section and special star rating systems and different HTML markup for your reviews.

POSTS = {
  ('posts/blog/*.md', blog', 'post.tmpl'),
  ('posts/food/*.md', 'food', 'post_recipe.tmpl'),
  ('posts/review/*.md', 'review, 'post_reviews.tmpl'),
}

Posts can’t be added to multiple sections as this might create duplicate pages with different addresses. Duplicate pages is something you will want to avoid in most cases. If you want a post to appear in multiple sections, you’re looking for Nikola’s tags or categories functionality.

Some customizations I’ve made to my own templates after reorganizing to use sections:

• Display the name and color of the section a post belongs to on the front page.
• Display a link to syndication feed for each section as well as the everything-feed at the top of each section and post belonging to that section.
• Breadcrumb navigations from posts to their sections and from the sections to the front page. Encourages visitors to your site to find more content from the same section.

Additionally, each section and every post in that section will be automatically assigned a color created by shifting the hue of the site’s THEME_COLOR option in the HUSL color space. This creates a visually similar color that can be used to style the posts and the sections in a uniform way, allowing each section to have a unique style of their own.

The color can be called from a theme using post.section_color() and can be used in an inline styles or a style element. The color manipulation functions can also be accessed directly in theme templates, allowing for shifting hue, saturation, or lightness of a given color. For example, a lighter version of a section’s color can be retrieved using color_hsl_adjust_hex( post.section_color(), adjust_l=0.05 ).

The options for controlling the behavior of sections are better documented in conf.py and include:

• POSTS_SECTIONS for enabling or disabling sections (on by default)
• POSTS_SECTION_ARE_INDEXES for making posts lists instead of indexes
• POSTS_SECTION_COLOR for manually assigning colors to sections rather than auto-generated colors from THEME_COLOR
• POSTS_SECTION_NAME for naming sections separately from their output folders
• POSTS_SECTION_TITLE for controlling the title of the section indexes
• POSTS_SECTION_DESCRIPTION for giving each section a description

There’s currently no way of generating a list of all sections. A site isn’t expected to need more than three–twelve sections at the most.

Sections will be available in Nikola version 7.7.0 due later this week.

Drop by the Nikola mailing list or chat room if you’ve built something cool with sections or just need a little help.