MkDocs plugins¶

api-autonav¶

Since 0.0.66

Generate API reference pages and navigation for Python modules with mkdocstrings.

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.

audio¶

Since 0.0.68

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

[project.plugins.mkdocs-audio]

plugins:
  - mkdocs-audio

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

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

For more information, see the plugin documentation.

autoapi¶

Since 0.0.66

Discover source files and generate API reference pages with mkdocstrings.

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.

autorefs¶

Since 0.0.22

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

For more information, see the plugin documentation.

awesome-nav¶

Since 0.0.58

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

Differences:

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

For more information, see the plugin documentation.

blog¶

Since 0.0.64

Publish posts with archives, categories, author profiles, and pagination. See Blog for setup and post metadata.

Differences:

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

For more information, see the plugin documentation.

callouts¶

Since 0.0.62

Render Obsidian-style callouts as admonitions.

Differences:

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

For more information, see plugin documentation.

exclude¶

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

Differences:

• Globs use glob patterns 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.

gh-admonitions¶

Since 0.0.67

Render GitHub-style alerts as admonitions. See GitHub callouts for the supported syntax.

Differences:

• The plugin entry enables pymdownx.quotes with callouts: true.
• important and caution use the default admonition style. See GitHub callouts for custom styling.

For more information, see plugin documentation.

glightbox¶

Since 0.0.35

Open images in a lightbox.

Differences:

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

For more information, see plugin documentation.

literate-nav¶

Since 0.0.58

Define navigation with Markdown lists of links.

For more information, see plugin documentation.

llmstxt¶

Since 0.0.67

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

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.

macros¶

Since 0.0.40

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

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, literate-nav, or 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.

markdown-exec¶

Since 0.0.47

Execute fenced code blocks and embed their output.

Install with:

pip install "markdown-exec[ansi]"

For more information, see plugin documentation.

markdownextradata¶

Since 0.0.69

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

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.

meta¶

Since 0.0.58

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

Differences:

• Custom YAML tags are not supported in metadata files.

For more information, see plugin documentation.

mike¶

Since 0.0.30

Publish and switch between documentation versions.

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 for installation and usage.

minify¶

Since 0.0.58

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

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.

mkdocstrings¶

Since 0.0.11

Generate API documentation from source code.

Install the Python handler with:

pip install mkdocstrings-python

Differences:

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

For more information, see plugin documentation.

nav-weight¶

Since 0.0.69

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

Differences:

• Weights are applied after other navigation plugins, regardless of their order in plugins.
• Resolved page metadata is used, including values inherited through 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.

offline¶

Since 0.0.3

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

For more information, see plugin documentation.

redirects¶

Since 0.0.58

Keep old links working when pages or sections move.

Differences:

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

For more information, see Redirects for examples.

rss¶

Since 0.0.65

Generate RSS and JSON feeds for new and updated pages.

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.

social¶

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

For more information, see plugin documentation.

search¶

Since 0.0.3

Add full-text search to your documentation.

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.

For more information, see site search.

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.

For more information, see Section index pages.

table-reader¶

Since 0.0.41

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

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.

tags¶

Since 0.0.58

Categorize pages and generate tag listings.

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.

For more information, see Tags configuration and the plugin documentation.

video¶

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

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

plugins:
  - mkdocs-video:
      is_video: true

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

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

For more information, see the plugin documentation.