mkdocs-pages-j2-plugin

This plugin builds .pages files from .pages.j2 files, using Jinja2 to render the templates. This plugin is particularly useful when used together with the mkdocs-awesome-pages-plugin.

Installation

Install the package with pip:

pip install mkdocs-pages-j2-plugin

Activate the plugin in mkdocs.yml:

plugins:
  - search
  - pages-j2
  - awesome-pages

Configuration

The plugin can be configured in the plugins section of mkdocs.yml as follows:

plugins:
  ...
  - pages-j2:
      use_extra: true
  ...

If use_extra is set to true (the default), the plugin will use the extra section of mkdocs.yml as context for rendering the templates. Otherwise, the plugin will use the full configuration.

Note that this feature has been added in version 0.3.0 and is a breaking change from version 0.2.x. Set use_extra to false if you want the same behaviour as in pre 0.3.0 versions.

Usage

Example of a .pages.j2 file:

title: Page Title
nav:
    - Welcome: index.md
{%- for i in range(1,3) %}
    - My Page {{ i }}: p{{ i }}.md
{%- endfor %}

The plugin will render the Jinja2 template above and create a .pages file with the following content:

title: Page Title
nav:
    - Welcome: index.md
    - My Page 1: p1.md
    - My Page 2: p2.md