Skip to content

Publishing a Knowledge Base

Every FreeDocStore knowledge base follows the same lifecycle: plan → repo → build → deploy → register.

Lifecycle

  1. Plan. Turn a topic into a concrete plan: KB id (slug), repo name, Cloudflare Pages project, production URL, first pages. The MCP publish_plan tool generates this plan without creating anything.
  2. Repo. Create a public GitHub repo under the FreeDocStore org named after the KB id, following the Zensical repo contract.
  3. Build. GitHub Actions installs Zensical and runs python -m zensical build --strict, producing static HTML in site/ (never committed).
  4. Deploy. The workflow deploys site/ to the Cloudflare Pages project named after the KB id, using the FreeDocStore org-level Actions secrets.
  5. Register. Add the KB to site/registry.json in the platform repo so the product site, MCP server, and agents can discover it.

The deploy workflow

Each KB repo carries .github/workflows/deploy.yml, triggered on push to main (and manual dispatch):

  1. Checkout, set up Python 3.12.
  2. python -m pip install zensical
  3. python -m zensical build --strict — strict mode fails the build on broken links or config errors.

  4. Source metadata injection — a Node script stamps every generated HTML page with:

    <meta name="source-repo" content="FreeDocStore/<kb-id>">
<meta name="source-path" content="docs/<page>.md">

    This maps each published page back to its Markdown source, which is what makes published pages agent-readable and editable from the Chrome extension.

  5. wrangler pages deploy site --project-name=<kb-id> via cloudflare/wrangler-action.

The Cloudflare step is conditional on CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID being available. These are org-level Actions secrets on the FreeDocStore GitHub org, visible to public repositories — a new public KB repo inherits them with no per-repo setup. If they are missing, the workflow prints a notice and skips deployment instead of failing.

Publishing checklist

  • Repo created under FreeDocStore/<kb-id>, public
  • zensical.toml at root with site_url set to the production URL
  • docs/index.md plus topic pages, listed in nav
  • .github/workflows/deploy.yml copied from an existing KB with --project-name=<kb-id>
  • .gitignore excludes site/, .cache/, __pycache__/
  • Cloudflare Pages project <kb-id> exists (first deploy creates the production branch)
  • Actions run is green and the site answers at https://<kb-id>.pages.dev/
  • Registry entry added to site/registry.json in the platform repo

Updating a published KB

Push to main — or merge a proposal PR — and the same workflow rebuilds and redeploys. There is no separate publish step. Agents can propose updates through the MCP update_files tool, which opens a reviewable PR by default.

Custom domains

Each KB's Pages project can attach custom domains; the registry records them in cloudflare.custom_domains. Domain automation is not built yet — attaching a domain is currently a manual Cloudflare step.