AI-Horde/zensical.toml

# SPDX-FileCopyrightText: 2026 Tazlin
#
# SPDX-License-Identifier: AGPL-3.0-or-later

# Static documentation site over docs/, built with Zensical (https://zensical.org).
# Navigation is curated below. docs/README.md is the landing page.
# Build with `uv run --only-group docs --locked zensical build`.
# preview with `uv run --only-group docs --locked zensical serve`.

[project]
site_name = "AI Horde"
site_description = "Implementation and operation documentation for the AI Horde service."
copyright = "AGPL-3.0-or-later"

# Local working notes are excluded from builds and previews.
exclude_docs = "/openai-chat-local/"

# Top-level sections mirror the documentation classes. Decision records deliberately enter
# navigation only through their generated index; the records are reached from the index,
# cross-links, and search, so navigation does not grow with the record count.
#
# Order and display titles here are curated. Membership is not: gen_doc_index.py --nav
# fails if a curated document is missing from this list, listed twice, absent from disk,
# or if a generated record is listed individually.
nav = [
    { "Home" = "README.md" },
    { "Explanation" = [
        { "Overview" = "explanation/README.md" },
        { "Kudos accounting" = "explanation/kudos_accounting.md" },
        { "Kudos retention" = "explanation/kudos_retention.md" },
        { "Request feasibility" = "explanation/request_feasibility_and_queue_pressure.md" },
        { "Chat requests" = "explanation/chat_requests.md" },
    ] },
    { "Reference" = [
        { "Overview" = "reference/README.md" },
        { "Kudos accounting" = "reference/kudos_accounting.md" },
        { "Samplers and schedulers" = "reference/samplers_and_schedulers.md" },
        { "Image baseline policy" = "reference/baseline_policy.md" },
        { "Image model reference loader" = "reference/model_reference.md" },
        { "Prompt provenance" = "reference/prompt_provenance.md" },
        { "Moderation operations" = "reference/moderation_operations.md" },
        { "Style contract" = "reference/style_contract.md" },
        { "Outbound requests" = "reference/outbound_requests.md" },
        { "Chat requests" = "reference/chat_requests.md" },
        { "Chat front" = "reference/chat_front.md" },
        { "Chat wire examples" = "reference/chat_wire_examples.md" },
    ] },
    { "How-to" = [
        { "Overview" = "how-to/README.md" },
        { "Kudos ledger operations" = "how-to/kudos_ledger_operations.md" },
        { "Extended image frontend" = "how-to/extended_image_frontend.md" },
        { "Add a sampler or annotator" = "how-to/add_sampler_or_annotator.md" },
        { "Add an image baseline" = "how-to/add_image_baseline.md" },
        { "Use the style endpoints" = "how-to/use_style_endpoints.md" },
        { "Add styles to a frontend" = "how-to/add_styles_to_a_frontend.md" },
        { "Update a style integration" = "how-to/update_a_style_integration.md" },
        { "Run the OpenAI-compatible chat front" = "how-to/run_openai_chat_front.md" },
        { "Send chat completions" = "how-to/send_chat_completions.md" },
        { "Send text generation requests" = "how-to/send_text_generation_requests.md" },
        { "Add chat to a frontend" = "how-to/add_chat_to_a_frontend.md" },
        { "Write a minimal chat worker" = "how-to/write_a_minimal_chat_worker.md" },
        { "Serve chat jobs" = "how-to/serve_chat_jobs.md" },
    ] },
    { "Tutorial" = [
        { "Overview" = "tutorial/README.md" },
        { "Your first chat completion" = "tutorial/first_chat_completion.md" },
        { "Serve your first chat job" = "tutorial/first_chat_worker.md" },
    ] },
    { "Topics" = "topics.md" },
    { "Decisions" = "decisions/index.md" },
    { "Concepts" = [
        { "Introduction" = "haidra-assets/docs/intro.md" },
        { "Why the Horde exists" = "haidra-assets/docs/why.md" },
        { "Definitions" = "haidra-assets/docs/definitions.md" },
        { "Workers" = "haidra-assets/docs/workers.md" },
        { "Job lifecycle" = "haidra-assets/docs/job_lifecycle.md" },
        { "Kudos" = "haidra-assets/docs/kudos.md" },
    ] },
    { "Standards" = [
        { "Documentation" = "haidra-assets/docs/meta/documentation.md" },
        { "Pull requests" = "haidra-assets/docs/meta/pull_requests.md" },
        { "Python" = "haidra-assets/docs/meta/python.md" },
    ] },
]

# `status` in a document's front matter puts a marker beside its navigation entry, with
# this text as the marker's tooltip. Only a planned document declares one, so the marker
# means "not yet written" wherever it appears.
[project.extra.status]
stub = "Not yet documented in full"

[project.theme]
language = "en"
logo = "haidra-assets/haidra-logo/haidra-logo-path.svg"
favicon = "haidra-assets/haidra-logo/haidra-transparent-zoomed-in.png"
features = [
    "content.code.copy",
    "content.tooltips",
    "navigation.footer",
    "navigation.indexes",
    "navigation.path",
    "navigation.tabs",
    "navigation.tabs.sticky",
    "navigation.top",
    "navigation.tracking",
    "search.highlight",
    "toc.follow",
]

[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"

[project.markdown_extensions.admonition]
[project.markdown_extensions.attr_list]
[project.markdown_extensions.def_list]
[project.markdown_extensions.footnotes]
[project.markdown_extensions.md_in_html]
[project.markdown_extensions.tables]
[project.markdown_extensions.toc]
permalink = true
[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
pygments_lang_class = true
[project.markdown_extensions.pymdownx.inlinehilite]
[project.markdown_extensions.pymdownx.magiclink]
[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
    { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
]
# Example programs under tools/, and sections of docs/reference/chat_wire_examples.md, are included into the pages
# that show them, so a page shows the code and bodies the tests check. check_paths fails the build when an included
# file is missing.
[project.markdown_extensions.pymdownx.snippets]
base_path = ["."]
check_paths = true