Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions docs/compatibility/mkdocs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,6 +474,32 @@ For more information, see [plugin documentation][markdown-exec].

---

### `markdownextradata`

_Since [0.0.69]_

Jinja templates are rendered in Markdown and page titles with project settings and `extra` variables.

<div class="mdx-plugin-settings" markdown>

| Setting | Default | Description |
| ------- | ------- | ----------- |
| `enabled` | `true` | Jinja rendering and data loading are enabled. |
| `data` | `null` | Comma-separated data directories, relative to the project root. When unset or empty, `_data` and `<docs_dir>/_data` are searched. |
| `jinja_options` | `{}` | Options passed to the Jinja environment, including template delimiters. |

</div>

**Differences**:

- Data directories and files that resolve outside the project root are silently skipped, including symlink targets.
- YAML data is loaded with `SafeLoader`. Python-specific tags such as `!!python/name` and `!!python/tuple` are rejected.
- YAML dates are converted to strings for theme templates. Their original Python types are retained during Markdown rendering.

For more information, see [plugin documentation][markdownextradata].

---

### `meta`

_Since [0.0.58]_
Expand Down Expand Up @@ -590,6 +616,36 @@ For more information, see [plugin documentation][mkdocstrings].

---

### `nav-weight`

_Since [0.0.69]_

Navigation order, section titles, and visibility are controlled through page metadata.

<div class="mdx-plugin-settings" markdown>

| Setting | Default | Description |
| ------- | ------- | ----------- |
| `enabled` | `true` | Weighted navigation is enabled. |
| `section_renamed` | `false` | Section names are replaced with their index page titles. |
| `index_weight` | `-10` | Weight assigned to index pages within their section. |
| `default_page_weight` | `0` | Weight assigned to pages with missing or invalid `weight` metadata. |
| `reverse` | `false` | Items are sorted from highest to lowest weight. |
| `headless_included` | `false` | Hidden pages are included in `nav.pages`. Empty index pages remain excluded. |
| `warning` | `true` | Warnings are emitted for invalid metadata values. |

</div>

**Differences**:

- Weights are applied after other navigation plugins, regardless of their order in `plugins`.
- Resolved page metadata is used, including values inherited through [`meta`](#meta) and changes made during Markdown rendering.
- Previous and next page links within hidden sections are rebuilt after hidden children are removed.

For more information, see [plugin documentation][mkdocs-nav-weight].

---

### `offline`

_Since [0.0.3]_
Expand Down Expand Up @@ -874,6 +930,12 @@ uvx --with mkdocs-gen-files python scripts/gen_ref_pages.py

This method requires a `mkdocs.yml` file. It does not work with `zensical.toml`.

### `open-in-new-tab`

The [`open-in-new-tab`][open-in-new-tab] plugin is not supported by Zensical.

Its [JavaScript code][open-in-new-tab JavaScript] can simply be added to your project with [`extra_javascript`][Additional JavaScript].

## Compatibility roadmap

We are closing the remaining compatibility gaps for widely used MkDocs and
Expand Down Expand Up @@ -915,6 +977,8 @@ without using their original codebases.
[0.0.66]: https://github.com/zensical/zensical/releases/tag/v0.0.66
[0.0.67]: https://github.com/zensical/zensical/releases/tag/v0.0.67
[0.0.68]: https://github.com/zensical/zensical/releases/tag/v0.0.68
[0.0.69]: https://github.com/zensical/zensical/releases/tag/v0.0.69
[Additional JavaScript]: ../../customization.md#additional-javascript
[api-autonav]: https://github.com/tlambert03/mkdocs-api-autonav#configuration
[audio]: https://github.com/jfcmontmorency/mkdocs-audio
[autoapi]: https://mkdocs-autoapi.readthedocs.io/en/latest/usage/
Expand All @@ -939,11 +1003,15 @@ without using their original codebases.
[llmstxt]: https://pawamoy.github.io/mkdocs-llmstxt/
[macros]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/
[markdown-exec]: https://github.com/pawamoy/markdown-exec
[markdownextradata]: https://github.com/rosscdh/mkdocs-markdownextradata-plugin
[meta]: https://squidfunk.github.io/mkdocs-material/plugins/meta/
[minify]: https://github.com/byrnereese/mkdocs-minify-plugin
[mkdocs-nav-weight]: https://github.com/shu307/mkdocs-nav-weight
[mkdocstrings]: https://mkdocstrings.github.io/
[not_in_nav]: https://github.com/zensical/backlog/issues/63
[offline]: https://squidfunk.github.io/mkdocs-material/plugins/offline/
[open-in-new-tab]: https://pypi.org/project/mkdocs-open-in-new-tab/
[open-in-new-tab JavaScript]: https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/blob/main/open_in_new_tab/js/open_in_new_tab.js
[optimize]: https://squidfunk.github.io/mkdocs-material/plugins/optimize/
[privacy]: https://squidfunk.github.io/mkdocs-material/plugins/privacy/
[pymdownx quotes]: https://facelessuser.github.io/pymdown-extensions/extensions/quotes/
Expand Down
Loading