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

plugins:
  - tags
  - minify:
      minify_html: true

If your project already uses zensical.toml:

[project.plugins.tags]

[project.plugins.minify]
minify_html = true

Validation and ignored settings¶

Zensical silently ignores the configuration for plugins that are not listed under Supported plugins. It does not import or run these plugins.

For a supported plugin, Zensical also silently ignores the settings that its entry identifies as ignored. Zensical does not validate their values or print a warning. It rejects any other unknown setting during configuration parsing.

Review each ignored setting before migration. The setting can remain in a configuration that is shared with MkDocs, but it has no effect when Zensical builds the site.

Unless an entry documents differences, the original plugin documentation (linked below) remains the reference for usage and configuration. We're working on shipping a growing list of supported plugins, as well as Zensical's own native public module API.

If you're lazy like us, use Zensical Studio to get completions and validation for all supported plugins directly in your editor inside zensical.toml and mkdocs.yml configuration files.

Supported plugins¶

Plugins are listed alphabetically. Most implementations require no additional installation. Each entry links to the original plugin documentation, where applicable, and to the Zensical release in which support was added.

autorefs¶

Since 0.0.22

See plugin documentation for usage and configuration.

Differences:

• Zensical ignores resolve_closest, link_titles, and strip_title_tags.

awesome-nav¶

Since 0.0.58

See plugin documentation for usage and configuration.

Differences:

• Extglob expressions are not supported; regular glob patterns are supported.
• MkDocs' not_in_nav setting is not supported.

blog¶

Since 0.0.64

See Blog for setup and the plugin documentation for all configuration options and post metadata.

Differences:

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

callouts¶

Since 0.0.62

See plugin documentation for the supported callout syntax.

Differences:

• The plugin entry enables pymdownx.quotes with callouts: true.
• Zensical ignores all three plugin settings: aliases, breakless_lists, and title_from_first_bold.

glightbox¶

Since 0.0.35

See plugin documentation for usage and configuration.

Differences:

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

literate-nav¶

Since 0.0.58

See plugin documentation for usage and configuration.

macros¶

Since 0.0.40

See plugin documentation for usage and configuration.

Differences:

• Referenced Python and YAML files must be inside the project directory.
• Zensical ignores force_render_paths and verbose.

markdown-exec¶

Since 0.0.47

Install with:

pip install "markdown-exec[ansi]"

See plugin documentation for usage and configuration.

meta¶

Since 0.0.58

See plugin documentation for usage and configuration.

Differences:

• Custom YAML tags are not supported in metadata files.

mike¶

Since 0.0.30

See Versioning with mike for installation, usage, and configuration.

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.

minify¶

Since 0.0.58

See plugin documentation for usage and configuration.

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.

mkdocstrings¶

Since 0.0.11

Install with:

pip install mkdocstrings-python

See plugin documentation for usage and configuration.

Differences:

• Backlinks are not supported.
• Sources outside the project directory are not watched during preview.
• Zensical ignores enable_inventory and watch.

offline¶

Since 0.0.3

See plugin documentation for usage and configuration.

redirects¶

Since 0.0.58

See Redirects for usage and configuration.

Differences:

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

search¶

Since 0.0.3

Zensical doesn't load the search plugin provided by MkDocs or Material for MkDocs. Both search and material/search configure Zensical's built-in site search module.

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

section-index¶

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

table-reader¶

Since 0.0.41

See plugin documentation for usage and configuration.

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.

tags¶

Since 0.0.58

See plugin documentation for usage and configuration.

Differences:

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

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.

Unsupported plugins¶

mkdocs-gen-files¶

Zensical does not currently support mkdocs-gen-files. 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:

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.

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¶

• social

Planned¶

• rss
• optimize
• exclude
• privacy
• git-authors
• git-committers
• git-revision-date-localized
• audio
• video

Review our public backlog 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.