Zensical¶

Zensical is a Python documentation framework built on MkDocs + Material — the default for mcp-zen-of-docs. All authoring primitives are supported natively; no extra packages required for admonitions, tabs, diagrams, or card grids.

Use Zensical when you write Python projects, want a docs-as-code pipeline, or need mkdocstrings API docs generated from source docstrings.

Detection¶

detect identifies Zensical from these signals, in priority order:

Key primitives¶

Admonitions — rendered by the admonition extension:

!!! note "Title"
    Content indented 4 spaces.

??? warning "Collapsible (click to expand)"
    Hidden until clicked. Requires `pymdownx.details`.

Content tabs — requires pymdownx.tabbed:

=== "Python"

    ```python
    print("hello")
    ```

=== "Bash"

    ```bash
    echo hello
    ```

Card grid — requires attr_list + md_in_html:

<div class="grid cards" markdown>

-   :material-star: **Card title**

    ---

    Description text.

    [:octicons-arrow-right-24: Learn more](page.md)

</div>

Extensions config¶

Add these to zensical.toml for full primitive support:

markdown_extensions = [
  "admonition",
  "attr_list",
  "md_in_html",
  "pymdownx.highlight",
  "pymdownx.superfences",
  "pymdownx.tabbed",
  "pymdownx.details",
  "pymdownx.emoji",
]

[project.theme.features]
"content.tabs.link" = true

Use the theme tool to generate this block automatically.

What scaffold produces¶

When scaffold runs in a Zensical project it emits:

• YAML frontmatter (title, description, tags)
• # Heading matching the title
• Framework-native admonitions (!!! note)
• Extension-aware code fences (```python)
• Nav entry appended to zensical.toml automatically

What to read next¶