Managing Docs with Zola

Use these conventions to keep Agentty documentation maintainable as it grows.

Keep URLs Stable🔗

  • Keep documentation under the content/docs/ section.
  • Keep the section directory named docs so its canonical route remains /docs/.
  • When moving or renaming pages, add aliases in page front matter to preserve old links.
  • For paragraph-level deep links, add explicit HTML anchors in content (for example, <a id="some-paragraph-id"></a> before the paragraph).
  • Paragraph anchors automatically render a # affordance next to the paragraph so users can copy deep links directly.

Use Section Metadata Deliberately🔗

  • Set sort_by = "weight" and define page weight values for intentional ordering.
  • Keep page_template on the docs section so all guides share a consistent layout.
  • Use in_search_index = true in docs sections, and ensure site-level search indexing is enabled when search is needed.

Scale with Nested Sections🔗

  • Group larger topics into nested sections (content/docs/<topic>/_index.md).
  • Render navigation from get_section(...).subsections so new sections appear automatically.
  • Use transparent = true only when subsection pages should be merged into the parent listing.

Prefer Mermaid for Diagrams🔗

  • Use fenced mermaid code blocks for flow, lifecycle, and architecture diagrams instead of ASCII trees.
  • Keep node labels concise and let the docs-page template handle theme-aware Mermaid rendering.
  • Mermaid diagrams in docs pages now ship with built-in fit, zoom, and drag-to-pan controls automatically, so authors do not need to add extra wrapper markup.

Add a Feature Entry🔗

The /features/ page auto-discovers entries from individual .md files in content/features/. To add a new feature:

  1. Add an E2E feature test with the FeatureTest builder in crates/agentty/tests/e2e/.
  2. Place the generated GIF in static/features/. FeatureTest writes this when VHS is installed; if GIF generation is skipped, do not add or keep the feature page until the matching asset exists.
  3. Create content/features/<name>.md with the following front matter:
    +++
title = "Feature title"
description = "One-line description shown on the card."
weight = <ordering number>

[extra]
gif = "<name>.gif"
+++
  4. Choose a weight that slots the entry into the desired display position (lower weights appear first).
  5. Run zola check to verify the features page renders the new entry.

The features.html template uses get_section(path="features/_index.md") and iterates section.pages ordered by weight. The homepage feature card in index.html is hardcoded and curated separately.

Authoring Workflow🔗

  1. Create a new Markdown page under content/docs/.
  2. Add title, description, and weight front matter.
  3. Add a <!-- more --> break so docs listings show concise summaries.
  4. Run zola check before publishing.