Nikola Documentation

Nikola is a flexible static site generator with the following capabilities:

• Content Formats: Supports reStructuredText, Markdown, Wiki, BBCode, Textile, and HTML.
• Blog Features: Built-in support for tags, feeds, archives, and comments.
• Extensibility: Highly extensible via a wide range of available plugins.
• Theming: Supports various themes for site customization.
• Media: Easy image gallery creation by placing files in folders.
• Multilingual: Supports sites translated into over 50 languages.
• Performance: Fast builds powered by doit.
• Syntax Highlighting: Supports syntax highlighting for most programming languages and markup.

Bootblog4 is a Nikola theme based on Bootstrap 4 and the Bootstrap blog example.

Important Notes:

• Icons: Icon fonts are not built-in. To use icons, you must integrate a library like Font Awesome manually.
• Customization: This theme does not support Bootswatch font or color schemes.

The Bootstrap 4 theme provides a simple navbar and content layout, making it a solid building block for a website. If you require a more blog-centric layout, consider using the bootblog4 theme instead.

Note on Icons: Unlike older versions of Bootstrap, icon fonts are not included by default. To use icons, you must integrate a library such as Font Awesome manually.

The bootblog4-jinja theme is based on Bootstrap 4 and the Bootstrap blog example.

Important considerations:

• Icons: Unlike previous Bootstrap versions, icon fonts are not built-in. To use icons, you must integrate a library like Font Awesome.
• Compatibility: This theme does not support Bootswatch font or color schemes.

Nikola themes are located in the themes folder of your installation or your site. A theme consists of several optional and one mandatory directory/file structure:

• assets/: Contains CSS, JavaScript, and image files (e.g., css/, js/, fonts/).
• templates/: Contains .tmpl files using Mako or Jinja2 template languages.
• messages/: Contains multilingual strings. For each language, create messages/messages_XX.py (where XX is the language code) containing a MESSAGES dictionary.
• less/ or sass/: Files to be compiled into CSS (requires plugins).
• <theme>.theme (Mandatory): An INI file containing theme metadata.
• bundles: An optional INI file used to combine multiple CSS/JS files into a single bundle for efficiency.
• parent / engine: (Legacy) One-line text files for older Nikola versions.

Nikola allows you to make data available to your templates through several mechanisms:

1. GLOBAL_CONTEXT in conf.py: Define variables here to make them available globally in all templates.
2. Data Directory: Place JSON, YAML, or TOML files in a data/ directory within your site. These files are decoded into Python dictionaries. For example, data/foo.json containing {"bar": "baz"} is accessed via ${data['foo']['bar']}.
3. Post-specific Data: Individual posts can have a data file specified via the data meta field. These are accessible via ${post.data['key']}.

Note: In shortcodes, use global_data instead of data to avoid name conflicts with the shortcode's internal content variable.

When rendering hierarchical taxonomies (like categories), use the indentation variables to build tree structures (e.g., nested HTML <ul> tags).

Each hierarchy item provides:

• indent levels: A list of pairs (current_i, count_i) representing the current position and maximum depth at level i.
• indent to change before: The difference in hierarchy levels between the previous and current item. A positive value indicates the current item is indented further (use this to open HTML tags like <ul>).
• indent to change after: The difference in hierarchy levels between the current and next item. A negative value indicates the current item is deeper than the next (use this to close HTML tags like </ul>).

Refer to tags.tmpl in the base themes for a concrete implementation example of rendering these as nested unordered lists.

reStructuredText supports two table syntaxes:

1. Grid tables: Complete and feature-rich, allowing for row and column spans, but more complex to construct manually.
2. Simple tables: Easier to create but limited (e.g., no row spans).

Grid Table Example

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | <span class="colspan">Cells may span columns.</span> |
+------------+------------+-----------+

Simple Table Example

=====  =====  ======
   Inputs     Output
------------  ------
   A         B    A or B
=====  =====  ======
False     False    False
True      False    True
=====  =====  ======

You can automate post scheduling by specifying an iCal recurrence rule in the SCHEDULE_RULE configuration setting.

To use this feature:

1. Set FUTURE_IS_NOW = False in your configuration.
2. Define SCHEDULE_RULE using the RRULE format.
3. Use the --schedule (or -s) flag with the new_post command to queue posts according to the rule.

Note: Queued posts will only appear online after you build and deploy your site (e.g., via a cron job).