# MkDocs plugins

Zensical provides native implementations of the MkDocs plugins listed below, meaning they continue to work with your existing configuration and project structure. In most cases, no additional packages are required as our implementations are behavior-preserving rewrites.

We aim to match their behavior as closely as possible and document the remaining differences. See the [compatibility roadmap](<#compatibility-roadmap>) for work in progress and planned support.

## Configuration

Most existing `mkdocs.yml` plugin configuration can remain unchanged. Review the differences below before migration. For example:

```yaml
plugins:
  - tags
  - minify:
      minify_html: true
```

If your project already uses `zensical.toml`:

```toml
[project.plugins.tags]

[project.plugins.minify]
minify_html = true
```

### Validation and ignored settings

- **Unsupported plugins:** Configuration for plugins not listed under [Supported plugins](<#supported-plugins>) is silently ignored. Zensical does not import or run them.
- **Ignored settings:** Settings marked as ignored in a plugin's differences are silently ignored, without value validation or warnings.
- **Unknown settings:** Supported plugins reject other unknown settings with a configuration error.

Review each plugin's differences before migrating. Ignored settings can remain in a shared MkDocs configuration, but have no effect in Zensical.

The tables below cover common settings; follow the documentation links for details. [Zensical Studio](<https://zensical.org/studio/>) provides completions and validation for supported plugins in both `zensical.toml` and `mkdocs.yml`.

## Supported plugins

Plugins are listed alphabetically. Most implementations require no additional installation. Each entry summarizes common settings, links to further documentation, and links to the Zensical release in which support was added.

> [!NOTE]
>
> **The plugin I need isn't listed. What can I do?**
>
> Check our [compatibility roadmap](<#compatibility-roadmap>) and public [backlog](<https://github.com/orgs/zensical/projects/2/views/1>) to see whether support is already planned. If it isn't, [create a change request](<https://github.com/zensical/zensical/issues/new/choose>) for the missing plugin in Zensical's issue tracker.

> [!NOTE]
>
> **Report issues to Zensical**
>
> Zensical reimplements MkDocs plugin behavior natively or integrates the original package where installation is required. If you encounter an issue when using these plugins with Zensical, [report it to us](<https://zensical.org/contributing/bug-reports/>).

### `api-autonav`

*Since [0.0.66](<https://github.com/zensical/zensical/releases/tag/v0.0.66>)*

Generate API reference pages and navigation for Python modules with [`mkdocstrings`](<#mkdocstrings>).

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable API reference generation. |
| `modules` | `[]` | Python files or package directories, relative to the project root. |
| `module_options` | `{}` | Handler options for modules matched by regular expressions. |
| `exclude` | `[]` | Module names or patterns to exclude; prefix regular expressions with `re:`. |
| `nav_section_title` | `API Reference` | Title of the generated navigation section. |
| `api_root_uri` | `reference` | Directory for generated API reference pages. |
| `exclude_private` | `true` | Exclude modules whose names start with an underscore. |
| `show_full_namespace` | `false` | Show full module names in navigation. |

**Differences**:

- `api_root_uri` must name a nonempty relative subdirectory. Empty strings, `.`, `./api`, absolute paths, and paths with `..` components are not supported.
- Source discovery skips child symlinks. It always excludes `.git`, `.venv`, `venv`, `__pycache__`, and the output and cache directories, regardless of include settings.

For more information, see the [plugin documentation](<https://github.com/tlambert03/mkdocs-api-autonav#configuration>).

---

### `audio`

> [!NOTE]
>
> **The plugin must be configured as `mkdocs-audio`.**

*Since [0.0.68](<https://github.com/zensical/zensical/releases/tag/v0.0.68>)*

Embed audio files with native browser playback controls. Configure the plugin as `mkdocs-audio`:

```toml
[project.plugins.mkdocs-audio]
```

```yaml
plugins:
  - mkdocs-audio
```

Use the configured marker as the image's alternative text:

```markdown
![type:audio](assets/audio.mp3)
```

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable audio embeds. |
| `mark` | `type:audio` | Image alternative text that identifies an audio embed. |
| `audio_type` | `mp3` | Audio MIME subtype, such as `mp3`, `wav`, or `ogg`. |
| `audio_controls` | `true` | Show playback controls. |
| `audio_autoplay` | `false` | Request automatic playback, subject to browser policies. |
| `audio_loop` | `false` | Repeat playback. |
| `css_style` | `{"width": "100%"}` | CSS properties applied to the audio element. |

For more information, see the [plugin documentation](<https://github.com/jfcmontmorency/mkdocs-audio>).

---

### `autoapi`

> [!NOTE]
>
> **The plugin must be configured as `mkdocs-autoapi`.**

*Since [0.0.66](<https://github.com/zensical/zensical/releases/tag/v0.0.66>)*

Discover source files and generate API reference pages with [`mkdocstrings`](<#mkdocstrings>).

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable automatic API documentation. |
| `autoapi_dir` | `.` | Source directory, relative to the project root. |
| `autoapi_file_patterns` | `["*.py", "*.pyi"]` | File patterns to include. |
| `autoapi_ignore` | `[]` | File patterns to exclude. |
| `autoapi_root` | `autoapi` | Directory for generated API reference pages. |
| `autoapi_add_nav_entry` | `true` | Add generated pages to navigation; a string sets the section title. |
| `autoapi_generate_api_docs` | `true` | Generate API reference pages. |
| `autoapi_keep_files` | `false` | Keep generated Markdown files in the documentation directory. |

**Differences**:

- `autoapi_root` must name a nonempty relative subdirectory. Empty strings, `.`, `./api`, absolute paths, and paths with `..` components are not supported.
- Source discovery skips child symlinks. It always excludes `.git`, `.venv`, `venv`, `__pycache__`, and the output and cache directories, regardless of include settings.

For more information, see the [plugin documentation](<https://mkdocs-autoapi.readthedocs.io/en/latest/usage/>).

---

### `autorefs`

*Since [0.0.22](<https://github.com/zensical/zensical/releases/tag/v0.0.22>)*

Link to headings and API objects across pages with `[text][identifier]`.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable automatic cross-references. |
| `resolve_closest` | `false` | Resolve duplicate identifiers to the closest page. |
| `link_titles` | `auto` | Link tooltips: `true`, `false`, `external`, or `auto`. With `auto`, only external links get tooltips when `navigation.instant.preview` is enabled; otherwise all links do. |
| `strip_title_tags` | `auto` | Strip HTML from tooltips: `true`, `false`, or `auto`. With `auto`, HTML is preserved when `content.tooltips` is enabled and stripped otherwise. |

For more information, see the [plugin documentation](<https://mkdocstrings.github.io/autorefs/>).

---

### `awesome-nav`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Customize navigation with a `.nav.yml` file in each documentation directory.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable directory-based navigation. |
| `filename` | `.nav.yml` | Name of the navigation configuration files. |
| `logs` | `{}` | Override message levels: `info`, `warning`, or `error`. Dotted settings below are nested here. |
| `logs.nav_override` | `warning` | Message when generated navigation replaces `nav`. |
| `logs.root_title` | `warning` | Message when `title` is set in the root navigation file. |
| `logs.root_hide` | `warning` | Message when `hide` is set in the root navigation file. |
| `logs.no_matches` | `warning` | Message when a glob pattern matches nothing. |

**Differences**:

- Extglob expressions are not supported; regular [glob patterns](<https://docs.rs/globset/latest/globset/#syntax>) are supported.
- The [`not_in_nav`](<https://zensical.org/docs/setup/basics/#not_in_nav>) setting is not applied to navigation generated by `awesome-nav`. Page visibility must be configured in `.nav.yml`.

For more information, see the [plugin documentation](<https://lukasgeiter.github.io/mkdocs-awesome-nav/>).

---

### `blog`

*Since [0.0.64](<https://github.com/zensical/zensical/releases/tag/v0.0.64>)*

Publish posts with archives, categories, author profiles, and pagination. See [Blog](<https://zensical.org/docs/setup/blog/index.md>) for setup and post metadata.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable the blog. |
| `blog_dir` | `blog` | Blog directory, relative to `docs_dir`. |
| `post_dir` | `{blog}/posts` | Posts directory, relative to `docs_dir`. |
| `post_url_format` | `{date}/{slug}` | Post URL template: `{date}`, `{slug}`, `{categories}`, `{file}`. |
| `post_excerpt_separator` | `<!-- more -->` | Marker separating the excerpt from the rest of a post. |
| `authors_profiles` | `false` | Generate author profile pages. |
| `pagination_per_page` | `10` | Posts per page. |
| `draft_on_serve` | `true` | Include drafts during preview. |

**Differences**:

- Custom Python callables aren't supported; built-in strategies are.

For more information, see the [plugin documentation](<https://zensical.org/docs/setup/blog/index.md>).

---

### `callouts`

*Since [0.0.62](<https://github.com/zensical/zensical/releases/tag/v0.0.62>)*

Render Obsidian-style callouts as admonitions.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable callouts. |

**Differences**:

- The plugin entry enables [`pymdownx.quotes`](<https://facelessuser.github.io/pymdown-extensions/extensions/quotes/>) with `callouts: true`.
- Zensical ignores all three plugin settings: `aliases`, `breakless_lists`, and `title_from_first_bold`.

For more information, see [plugin documentation](<https://github.com/sondregronas/mkdocs-callouts>).

---

### `exclude`

*Since [0.0.67](<https://github.com/zensical/zensical/releases/tag/v0.0.67>)*

Exclude files from the generated site by path pattern.

Patterns match source paths relative to `docs_dir`. Exclusion also applies to generated API pages and theme assets. Regular expressions match from the start of each path.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable file exclusion. |
| `glob` | `[]` | Glob patterns for paths to exclude. |
| `regex` | `[]` | Regular expressions for paths to exclude. |

**Differences**:

- Globs use [glob patterns](<https://docs.rs/globset/latest/globset/#syntax>) syntax, as in `awesome-nav`. `**` matches directories recursively, and `{a,b}` selects alternatives. As in the original exclude plugin, `*` also matches directory separators.
- Backslashes escape glob characters. Use `/` as the directory separator.
- Invalid glob patterns are rejected.

For more information, see [plugin documentation](<https://github.com/apenwarr/mkdocs-exclude>).

---

### `gh-admonitions`

*Since [0.0.67](<https://github.com/zensical/zensical/releases/tag/v0.0.67>)*

Render GitHub-style alerts as admonitions. See [GitHub callouts](<https://zensical.org/docs/authoring/admonitions/#github-callouts>) for the supported syntax.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable GitHub-style admonitions. |

**Differences**:

- The plugin entry enables [`pymdownx.quotes`](<https://facelessuser.github.io/pymdown-extensions/extensions/quotes/>) with `callouts: true`.
- `important` and `caution` use the default admonition style. See [GitHub callouts](<https://zensical.org/docs/authoring/admonitions/#github-callouts>) for custom styling.

For more information, see [plugin documentation](<https://pypi.org/project/mkdocs-github-admonitions-plugin/>).

---

### `glightbox`

*Since [0.0.35](<https://github.com/zensical/zensical/releases/tag/v0.0.35>)*

Open images in a lightbox.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable the lightbox. |
| `auto` | `true` | Enable the lightbox for images automatically. |
| `manual` | `null` | When `true`, only enable images marked with `on-glb`; overrides `auto`. |
| `auto_themed` | `false` | Group images by their light or dark theme variant. |
| `auto_caption` | `false` | Use image alt text as the caption. |
| `caption_position` | `bottom` | Caption position: `bottom`, `top`, `left`, or `right`. |
| `skip_classes` | `[]` | Additional image classes to exclude from the lightbox. |

**Differences**:

- Zensical ignores `touchNavigation`, `loop`, `effect`, `slide_effect`, `zoomable`, `draggable`, `background`, and `shadow`.

For more information, see [plugin documentation](<https://blueswen.github.io/mkdocs-glightbox/>).

---

### `include-markdown`

*Since [0.0.71](<https://github.com/zensical/zensical/releases/tag/v0.0.71>)*

Include Markdown files and other text content in your documentation.

The `{% include-markdown "file.md" %}` and `{% include "file.txt" %}` tags are converted to [Snippets](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/>) directives before Markdown processing. Tags must be placed on their own lines; multiline tags and tags inside fenced code blocks are supported.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Whether include tags are processed. |
| `opening_tag` / `closing_tag` | `{%` / `%}` | Delimiters used around include tags. |
| `directives` | `{}` | Directive names can be changed through the `include` and `include-markdown` keys. |
| `encoding` | `utf-8` | Encoding used for included files. |
| `include_from_url` | `true` | Whether content can be included from HTTP and HTTPS URLs. |
| `preserve_includer_indent` | `true` | Whether included content is indented to match its tag. |
| `dedent` | `false` | Whether common leading whitespace is removed from included content. |

**Differences**:

- **Per-inclusion settings:** Per-inclusion arguments are accepted but ignored. Supported defaults must be configured globally under `plugins.include-markdown` or `markdown_extensions.pymdownx.snippets`.
- **Snippets configuration:** Snippets is enabled automatically. Explicit Snippets settings are given precedence over mapped plugin settings, including path restrictions, encoding, dedenting, URL downloads, and missing-file handling.
- **Paths and recursion:** Paths are resolved relative to `docs_dir`; paths beginning with `./` or `../` are resolved relative to the including file. Absolute paths and recursive includes are supported. Repeated files in an inclusion chain are skipped. Glob patterns are not supported, and `exclude`, `order`, and `recursive` are ignored. Relative paths in remote includes are resolved against the including URL.
- **Content selection:** The `start` and `end` settings and arguments are ignored. Content sections and line ranges can be selected with native [Snippets notation](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/>).
- **Content transformations:** Links are resolved relative to the including page, and heading levels are preserved. The `rewrite_relative_urls`, `heading_offset`, `comments`, and `trailing_newlines` settings are ignored. Include comments are not inserted, and trailing newlines are preserved by Snippets.
- **Downloads and rebuilds:** The `cache` and `cache_dir` settings are ignored; downloads are cached by Snippets for each Markdown conversion. Included files outside `docs_dir` must be added to [`watch`](<https://zensical.org/docs/setup/basics/#watch>) for live rebuilding.

For more information, see the [plugin documentation](<https://pypi.org/project/mkdocs-include-markdown-plugin/7.3.0/>) and [PyMdown Snippets](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/>).

---

### `literate-nav`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Define navigation with Markdown lists of links.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable Markdown-based navigation. |
| `nav_file` | `SUMMARY.md` | Name of the navigation file. |
| `implicit_index` | `false` | Include each directory's index page automatically. |
| `tab_length` | `4` | Spaces per indentation level in navigation lists. |
| `markdown_extensions` | `[]` | Additional Markdown extensions for parsing navigation files. |

For more information, see [plugin documentation](<https://oprypin.github.io/mkdocs-literate-nav/>).

---

### `llmstxt`

*Since [0.0.67](<https://github.com/zensical/zensical/releases/tag/v0.0.67>)*

An `llms.txt` index and Markdown copies of selected pages are generated.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable `llms.txt` generation. |
| `sections` | Required | Named sections and source pages to include; page paths can contain glob patterns. |
| `markdown_description` | `null` | Markdown description added after the site description. |
| `base_url` | `site_url` | Base URL used for links to generated Markdown pages. |
| `full_output` | `null` | Path of an optional file containing the full text of selected pages. |
| `autoclean` | `true` | Clean generated HTML before conversion to Markdown. |

**Differences**:

- With `content.action.copy` in the theme's `features` list, a "Copy as Markdown" button is shown on pages with a Markdown equivalent.
- Zensical silently ignores `preprocess`. Custom Python preprocessing functions are not run.
- mkdocstrings source listings and empty code elements are omitted, even with `autoclean: false`.
- `full_output` must be a relative file path inside `site_dir`, different from `llms.txt`. Absolute paths and empty, `.` or `..` path components are rejected.

For more information, see [plugin documentation](<https://pawamoy.github.io/mkdocs-llmstxt/>).

---

### `macros`

*Since [0.0.40](<https://github.com/zensical/zensical/releases/tag/v0.0.40>)*

Jinja variables, filters, and Python macros are supported in Markdown.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable macros. |
| `module_name` | `main` | Local Python module, loaded after `modules`. Its definitions are given precedence. |
| `modules` | `[]` | Importable packages, loaded in order. Failed imports are reported as errors. |
| `include_yaml` | `[]` | YAML files providing variables. |
| `include_dir` | `""` | Directory for Jinja includes and imports, relative to the project root. If empty, `docs_dir` is used. |
| `render_by_default` | `true` | Render Jinja on all pages unless their metadata overrides it. |
| `force_render_paths` | `""` | Additional pages selected for Jinja rendering with multiline [file patterns](<https://zensical.org/docs/setup/basics/#file-patterns>), relative to `docs_dir`. Page metadata takes precedence. |
| `on_error_fail` | `false` | With `true`, the build is stopped on rendering errors. With `false`, error diagnostics are inserted into the page. |
| `on_undefined` | `keep` | With `keep`, simple undefined expressions are preserved. With `silent`, undefined values are rendered as empty strings. With `strict`, errors are raised. With `lax`, missing attributes are also rendered as empty strings. |

**Differences**:

- **Environment lifetime:** A new macro environment is created for each page rendered, and `define_env(env)` is called for that page. Updates to `env.variables` are not carried over to another page. Counters initialized in `define_env` are reset for the next rendered page. In MkDocs Macros, the environment is initialized once per build.
- **Macro context:** Limited page objects are provided through `env.page` and the Jinja `page` variable, with `url`, `path`, `title`, and `meta`. MkDocs attributes such as `page.file` are not provided. Plain dictionaries are supplied through `env.conf` and `env.config`. Empty lists are supplied for `navigation` and `files`.
- **Module hooks and APIs:** Only `define_env` is called automatically. `on_pre_page_macros`, `on_post_page_macros`, and `on_post_build` are not called. APIs such as `env.markdown`, `env.render()`, `env.env`, and `env.register_variables()` are not provided.
- **Generated navigation titles:** Titles assigned by [`awesome-nav`](<#awesome-nav>), [`literate-nav`](<#literate-nav>), or [`autoapi`](<#autoapi>) are resolved after macros. During macro rendering, `env.page.title` is derived from metadata, the source heading, or the filename.
- **External files:** Local Python modules are resolved from the project directory. Included YAML files must be inside that directory and contain a mapping. Missing YAML files are silently ignored.
- **YAML variables:** A list of file paths or a mapping such as `{data: data.yaml}` is accepted for `include_yaml`. MkDocs Macros' list entries such as `- data: data.yaml` are not accepted. Existing keys are replaced without recursive merging. Page-level `include_yaml` is also supported.

For more information, see [plugin documentation](<https://mkdocs-macros-plugin.readthedocs.io/en/latest/>).

---

### `markdown-exec`

*Since [0.0.47](<https://github.com/zensical/zensical/releases/tag/v0.0.47>)*

Execute fenced code blocks and embed their output.

Install with:

```sh
pip install "markdown-exec[ansi]"
```

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable code block execution. |
| `ansi` | `false` | ANSI output support: `true`, `false`, `auto`, `off`, or `required`; enabled modes require `pygments-ansi-color`. |
| `languages` | `null` | Languages to execute; unset enables all supported languages, `[]` disables execution. |

For more information, see [plugin documentation](<https://github.com/pawamoy/markdown-exec>).

---

### `markdownextradata`

*Since [0.0.69](<https://github.com/zensical/zensical/releases/tag/v0.0.69>)*

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

| 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. |

**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](<https://github.com/rosscdh/mkdocs-markdownextradata-plugin>).

---

### `meta`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Apply shared front matter to pages in a directory and its subdirectories.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable shared metadata. |
| `meta_file` | `.meta.yml` | Metadata file name. |

**Differences**:

- Custom YAML tags are not supported in metadata files.

For more information, see [plugin documentation](<https://squidfunk.github.io/mkdocs-material/plugins/meta/>).

---

### `mike`

*Since [0.0.30](<https://github.com/zensical/zensical/releases/tag/v0.0.30>)*

Publish and switch between documentation versions.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable mike integration. |
| `version_selector` | `true` | Show the version selector. |
| `alias_type` | `symlink` | Alias type: `symlink`, `redirect`, or `copy`. |
| `deploy_prefix` | `""` | Directory prefix for versioned deployments. |
| `canonical_version` | `null` | Version used for canonical URLs. |
| `redirect_template` | `null` | Custom template for redirect aliases. |

**Differences**:

- Zensical requires the compatible fork described in the versioning guide.
- Zensical ignores `css_dir` and `javascript_dir` because it provides the version selector assets.

For more information, see [Versioning with mike](<https://zensical.org/docs/compatibility/mkdocs/mike/index.md>) for installation and usage.

---

### `minify`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Reduce the size of generated HTML, JavaScript, and CSS.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable minification. |
| `minify_html` | `false` | Minify generated HTML. |
| `minify_js` | `false` | Minify files listed in `js_files`. |
| `minify_css` | `false` | Minify files listed in `css_files`. |
| `js_files` | `[]` | JavaScript files to minify. |
| `css_files` | `[]` | CSS files to minify. |
| `minify_inline_js` | `false` | Minify JavaScript inside `<script>` elements. |
| `minify_inline_css` | `false` | Minify CSS inside `<style>` elements. |

**Differences**:

- Assets that cannot be parsed retain their original content instead of crashing the build.
- `minify_inline_js` and `minify_inline_css` are Zensical-only options. They minify JavaScript in `<script>` elements and CSS in `<style>` elements.

For more information, see [plugin documentation](<https://github.com/byrnereese/mkdocs-minify-plugin>).

---

### `mkdocstrings`

*Since [0.0.11](<https://github.com/zensical/zensical/releases/tag/v0.0.11>)*

Generate API documentation from source code.

Install the Python handler with:

```sh
pip install mkdocstrings-python
```

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable API documentation. |
| `default_handler` | `python` | Handler used when a directive does not specify one. |
| `handlers` | `{}` | Handler configuration. |
| `custom_templates` | `null` | Directory containing custom handler templates. |
| `enable_inventory` | `null` | Generate `objects.inv`; unset follows the handlers' inventory settings. |
| `locale` | `en` | Language used by handlers. |

**Differences**:

- Sources outside the project directory are not watched during preview.
- Zensical ignores `watch`.

For more information, see [plugin documentation](<https://mkdocstrings.github.io/>).

---

### `nav-weight`

> [!NOTE]
>
> **The plugin must be configured as `mkdocs-nav-weight`.**

*Since [0.0.69](<https://github.com/zensical/zensical/releases/tag/v0.0.69>)*

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

| 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. |

**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](<https://github.com/shu307/mkdocs-nav-weight>).

---

### `offline`

*Since [0.0.3](<https://github.com/zensical/zensical/releases/tag/v0.0.3>)*

Make the site searchable when opened directly from the file system.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable offline search support. |

For more information, see [plugin documentation](<https://squidfunk.github.io/mkdocs-material/plugins/offline/>).

---

### `redirects`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Keep old links working when pages or sections move.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable redirects. |
| `redirect_maps` | `{}` | Map old paths to new paths or URLs. |

**Differences**:

- Zensical supports anchor-based redirects for moving sections and splitting pages.

For more information, see [Redirects](<https://zensical.org/docs/setup/redirects/index.md>) for examples.

---

### `rss`

*Since [0.0.65](<https://github.com/zensical/zensical/releases/tag/v0.0.65>)*

Generate RSS and JSON feeds for new and updated pages.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable feed generation. |
| `feed_title` | `site_name` | Feed title; defaults to the site name. |
| `length` | `20` | Maximum entries in each feed. |
| `match_path` | `.*` | Regular expression selecting page paths to include. |
| `abstract_chars_count` | `160` | Maximum summary length; `-1` includes the full content. |
| `date_from_meta` | Git dates | Metadata fields and formats for creation and update dates. |

**Differences**:

- Zensical ignores `cache_dir` and does not fetch remote images for RSS enclosures.
- Zensical ignores `use_material_social_cards`; generated social cards are not used.

For more information, see [plugin documentation](<https://guts.github.io/mkdocs-rss-plugin/>).

---

### `social`

*Since [0.0.67](<https://github.com/zensical/zensical/releases/tag/v0.0.67>)*

Generate social cards and Open Graph metadata for pages. Set `site_url` to link the generated cards in page metadata. Page front matter can override `cards`, `cards_layout`, and `cards_layout_options` under `social`.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable social card generation. |
| `cards` | `true` | Generate cards for pages by default. |
| `cards_dir` | `assets/images/social` | Site directory for generated cards. |
| `cards_layout` | `default` | Card layout to render. |
| `cards_layout_dir` | `layouts` | Project directory for custom layouts. |
| `cards_layout_options` | `{}` | Values passed to card layouts. |
| `cards_include` | `[]` | Source path patterns selecting pages for cards. |
| `cards_exclude` | `[]` | Source path patterns excluding pages from cards. |
| `cache` | `true` | Cache generated cards between builds. |
| `cache_dir` | `.cache/plugin/social` | Project directory for cached cards. |

For more information, see [plugin documentation](<https://squidfunk.github.io/mkdocs-material/plugins/social/>).

---

### `search`

*Since [0.0.3](<https://github.com/zensical/zensical/releases/tag/v0.0.3>)*

Add full-text search to your documentation.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable search. |
| `separator` | Built-in pattern | Regular expression splitting text at whitespace and punctuation. |

**Differences**:

- Search is enabled by default, even when it isn't listed under `plugins`.
- `enabled` and `separator` are the only plugin settings that affect Zensical search.
- Zensical ignores `lang`. It takes the search language from [`theme.language`](<https://zensical.org/docs/setup/language/#site-language>).
- Zensical ignores `pipeline`. It has no equivalent because Zensical's search engine does not use the Lunr pipeline.
- Zensical ignores `fields`, `indexing`, `jieba_dict`, `jieba_dict_user`, `min_search_length`, and `prebuild_index`.

For more information, see [site search](<https://zensical.org/docs/setup/search/index.md>).

---

### `section-index`

*Since [0.0.3](<https://github.com/zensical/zensical/releases/tag/v0.0.3>)*

Zensical provides section-index behavior natively. You can keep the `section-index` plugin entry in a shared configuration, but Zensical ignores the entry.

| Setting | Default | Description |
| --- | --- | --- |
| Configuration | — | No plugin settings are required. |

For more information, see [Section index pages](<https://zensical.org/docs/setup/navigation/#section-index-pages>).

---

### `table-reader`

*Since [0.0.41](<https://github.com/zensical/zensical/releases/tag/v0.0.41>)*

Embed data files as Markdown tables with reader calls such as `{{ read_csv('table.csv') }}`.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable table readers. |
| `data_path` | `.` | Base directory for data files. |
| `allow_missing_files` | `false` | Continue building when a table file is missing. |
| `select_readers` | All supported readers | Readers to enable. |

**Differences**:

- `data_path` and all table files must be inside the project directory.
- Reader call arguments must be Python literals. Names, expressions, and `**kwargs` expansion are not supported.

For more information, see [plugin documentation](<https://timvink.github.io/mkdocs-table-reader-plugin/>).

---

### `tags`

*Since [0.0.58](<https://github.com/zensical/zensical/releases/tag/v0.0.58>)*

Categorize pages and generate tag listings.

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable tags. |
| `tags` | `true` | Show tags on pages. |
| `tags_allowed` | `[]` | Allowed tags; an empty list allows all. |
| `tags_hierarchy` | `false` | Enable hierarchical tags. |
| `tags_sort_by` | `tag_name` | Tag sorting strategy. |
| `listings` | `true` | Generate listings where `<!-- material/tags -->` is placed. |
| `listings_sort_by` | `item_title` | Sort pages within listings. |
| `listings_toc` | `true` | Add listing tags to the table of contents. |

**Differences**:

Zensical silently ignores the legacy settings below. Rename or replace them so that their behavior applies to a Zensical build.

| Ignored setting | Migration |
| --- | --- |
| `tags_compare` | Use [`tags_sort_by`](<https://zensical.org/docs/setup/tags/#configuration>). |
| `tags_compare_reverse` | Use [`tags_sort_reverse`](<https://zensical.org/docs/setup/tags/#configuration>). |
| `tags_pages_compare` | Use [`listings_sort_by`](<https://zensical.org/docs/setup/tags/#configuration>). |
| `tags_pages_compare_reverse` | Use [`listings_sort_reverse`](<https://zensical.org/docs/setup/tags/#configuration>). |
| `tags_file` | Add `<!-- material/tags -->` to the tag index page. |
| `tags_extra_files` | Add a `<!-- material/tags -->` directive to each extra tag index page. |
| `export` | No replacement. Native tags do not export JSON. |
| `export_file` | No replacement. Native tags do not export JSON. |
| `export_only` | No replacement. Native tags do not export JSON. |

Custom Python callables for `tags_slugify`, `tags_sort_by`, `listings_sort_by`, and `listings_tags_sort_by` are not supported. Use one of the built-in callables documented by Material for MkDocs.

For more information, see [Tags configuration](<https://zensical.org/docs/setup/tags/#configuration>) and the [plugin documentation](<https://squidfunk.github.io/mkdocs-material/plugins/tags/>).

---

### `video`

> [!NOTE]
>
> **The plugin must be configured as `mkdocs-video`.**

*Since [0.0.68](<https://github.com/zensical/zensical/releases/tag/v0.0.68>)*

Embed remote players using an iframe or video files with native browser playback controls. Configure the plugin as `mkdocs-video`; set `is_video` to `true` for native video playback:

```toml
[project.plugins.mkdocs-video]
is_video = true
```

```yaml
plugins:
  - mkdocs-video:
      is_video: true
```

Use the configured marker as the image's alternative text:

```markdown
![type:video](assets/video.mp4)
```

| Setting | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable video embeds. |
| `mark` | `type:video` | Image alternative text that identifies a video embed. |
| `is_video` | `false` | Use a native video element instead of an iframe. |
| `video_type` | `mp4` | Native video MIME subtype, such as `mp4`, `webm`, or `ogg`. |
| `video_controls` | `true` | Show native video playback controls. |
| `video_autoplay` | `false` | Request automatic native video playback, subject to browser policies. |
| `video_loop` | `false` | Repeat native video playback. |
| `video_muted` | `false` | Mute native video playback. |
| `css_style` | `{"position": "relative", "width": "100%", "height": "22.172vw"}` | CSS properties applied to the iframe or video element. |

For more information, see the [plugin documentation](<https://github.com/soulless-viewer/mkdocs-video>).

## Unsupported plugins

### `gen-files`

Zensical does not currently support [`gen-files`](<https://oprypin.github.io/mkdocs-gen-files/>).

To create API reference pages automatically, use [`autoapi`](<#autoapi>) or [`api-autonav`](<#api-autonav>). Both generate API reference pages and navigation with `mkdocstrings`.

For other uses, run the generation scripts separately from the Zensical build. You can run them once or regularly. Track the generated files in version control.

You do not need to add `mkdocs-gen-files` to your project dependencies. Use `uvx` to run a script:

```sh
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`](<https://pypi.org/project/mkdocs-open-in-new-tab/>) plugin is not supported by Zensical.

Its [JavaScript code](<https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/blob/main/open_in_new_tab/js/open_in_new_tab.js>) can simply be added to your project with [`extra_javascript`](<https://zensical.org/docs/customization/#additional-javascript>).

## Compatibility roadmap

We are closing the remaining compatibility gaps for widely used MkDocs and Material for MkDocs plugins. These statuses reflect our current priorities and do not imply release dates.

### In progress

- [ ] [`optimize`](<https://squidfunk.github.io/mkdocs-material/plugins/optimize/>)

### Planned

- [ ] [`privacy`](<https://squidfunk.github.io/mkdocs-material/plugins/privacy/>)
- [ ] [`git-authors`](<https://timvink.github.io/mkdocs-git-authors-plugin/>)
- [ ] [`git-committers`](<https://github.com/byrnereese/mkdocs-git-committers-plugin>)
- [ ] [`git-revision-date-localized`](<https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/>)

*Review our public [backlog](<https://github.com/orgs/zensical/projects/2/views/1>) for additional plugins we may support later.*

## Acknowledgements

We thank all plugin authors and contributors for building and maintaining the MkDocs plugin ecosystem. Where Zensical provides native implementations, they are bottom-up rewrites that reproduce the plugins' configuration and behavior without using their original codebases.