John Lancaster
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# 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.
|
|
|
|
!!! info "Source links"
|
|
- [Zensical navigation setup](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.
|
|
|
|
!!! info "Source links"
|
|
- [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
|
|
- [mkdocstrings](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.
|
|
|
|
!!! info "Source links"
|
|
- [Zensical content tabs](https://zensical.org/docs/authoring/content-tabs/)
|
|
- [Zensical tooltips](https://zensical.org/docs/authoring/tooltips/)
|
|
- [Zensical footnotes](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).
|
|
|
|
!!! info "Source links"
|
|
- [Zensical search setup](https://zensical.org/docs/setup/search/)
|
|
- [Zensical repository setup](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.
|
|
|
|
!!! info "Source links"
|
|
- [Zensical customization overview](https://zensical.org/docs/customization/)
|
|
- [Additional CSS](https://zensical.org/docs/customization/#additional-css)
|
|
- [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
|
|
- [Extending the theme](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.
|