Metadata-Version: 2.1
Name: mkdocs-pages-j2-plugin
Version: 0.3.1
Summary: An MkDocs plugin to generate '.pages' from 'pages.j2'
Home-page: https://github.com/supcik/mkdocs-pages-j2-plugin
License: Apache-2
Keywords: mkdocs,python,markdown,wiki
Author: Jacques Supcik
Author-email: jacques.supcik@hefr.ch
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Provides-Extra: test
Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: mkdocs (>=1.5.3,<2.0.0)
Requires-Dist: mkdocs-awesome-pages-plugin (>=2.9.2,<3.0.0) ; extra == "test"
Requires-Dist: mkdocs-macros-plugin (>=1.0.4,<2.0.0) ; extra == "test"
Requires-Dist: mkdocs-material (>=9.4.2,<10.0.0) ; extra == "test"
Project-URL: Repository, https://github.com/supcik/mkdocs-pages-j2-plugin
Description-Content-Type: text/markdown

# 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](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin).

## Installation

Install the package with pip:

```bash
pip install mkdocs-pages-j2-plugin
```

Activate the plugin in `mkdocs.yml`:

```yaml
plugins:
  - search
  - pages-j2
  - awesome-pages
```

## Configuration

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

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

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

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

