prompts/docs/skills/zensical-docs/references/zensical-features.md

Zensical Features and Configuration Patterns

Use this reference when deciding which Zensical features to enable and why.

Project Bootstrap

Always start a new docs project with uv run zensical new.

• It creates the baseline scaffolding for configuration, docs structure, and theme integration.
• Treat this as the default starting point rather than manually assembling files.

High-Value Feature Groups

Navigation and Discoverability

• navigation.indexes: lets sections have index pages for overview content.
• navigation.path: adds breadcrumb-like context.
• navigation.sections: groups top-level sections for large doc sets.
• navigation.instant: enables instant internal navigation.
• navigation.instant.prefetch: prefetches likely next pages.
• navigation.top: shows a back-to-top affordance.
• navigation.tracking: keeps URL anchors in sync with active section.

Source links:

• https://zensical.org/docs/setup/navigation/

Code-Heavy Documentation

• content.code.copy: copy button in code blocks.
• content.code.select: line range selection support.
• content.code.annotate: inline code annotations.
• Prefer mkdocstrings for generated API reference pages when documenting Python code.
• Keep generated API pages linked from hand-authored task and concept docs.

Source links:

• https://zensical.org/docs/authoring/code-blocks/
• https://mkdocstrings.github.io/

Cross-Page UX Consistency

• content.tabs.link: keeps same-named tabs synchronized.
• content.tooltips: improves tooltip behavior for links.
• content.footnote.tooltips: inline footnote previews.

Source links:

• https://zensical.org/docs/authoring/content-tabs/
• https://zensical.org/docs/authoring/tooltips/
• https://zensical.org/docs/authoring/footnotes/

Search and Content Actions

• search.highlight: highlights matches after search navigation.
• content.action.edit and content.action.view (if repository integration is configured).

Source links:

• https://zensical.org/docs/setup/search/
• https://zensical.org/docs/setup/repository/

Styling and Extensibility

Use site-level customization when docs need stronger visual affordances.

• extra_css: add targeted style overrides.
• extra_javascript: add behavior enhancements.
• Theme override directory (custom_dir) for template-level changes.

Source links:

• https://zensical.org/docs/customization/
• https://zensical.org/docs/customization/#additional-css
• https://zensical.org/docs/customization/#additional-javascript
• https://zensical.org/docs/customization/#extending-the-theme

Practical Feature Selection Rules

1. Start with discoverability and clarity features first.
2. For code-heavy docs, add copy/select/annotate first, then define mkdocstrings coverage for API reference.
3. Avoid enabling many features at once without measurement.
4. Track user success metrics (search success, time-to-answer, support deflection) after each change.