Zensical Repo Contract¶

FreeDocStore publishes Zensical-format Markdown repositories only. A KB repo must match this contract; the MCP check_zensical_repo tool validates it.

Required layout¶

<kb-repo>/
├── README.md
├── zensical.toml              # Zensical config at repo root
├── .gitignore                 # excludes site/, .cache/, __pycache__/
├── .github/workflows/deploy.yml
└── docs/
    ├── index.md               # required
    └── <topic-pages>.md

Rules¶

• One GitHub repo per knowledge base.
• Markdown source lives in docs/ (docs_dir = "docs").
• zensical.toml sits at the repo root (config = "zensical.toml" in the registry).
• Zensical builds to site/ (site_dir = "site"); the generated site/ directory is never committed.
• No embedded static HTML docs — docs/ contains Markdown only.
• Build command: python -m pip install zensical && python -m zensical build --strict.
• Each KB has its own Cloudflare Pages project, named after the KB id.
• The platform repo stores registry metadata only; KB content never lives in the platform repo.

Validation¶

check_zensical_repo checks:

zensical.toml essentials¶

[project]
site_name = "My Knowledge Base"
site_url = "https://<kb-id>.pages.dev/"
repo_url = "https://github.com/FreeDocStore/<kb-id>"
docs_dir = "docs"
site_dir = "site"

nav = [
  { "Start" = "index.md" },
  { "Topic" = "topic.md" }
]

Theme palettes (light/dark), navigation features, and Markdown extensions (admonitions, footnotes, task lists, code highlighting via pymdownx) follow the existing KBs — copy zensical.toml from a published KB such as true-non-profit and adjust.