Skip to content

Documentation Site

1. Decision

After the one-time publication gate, Fgentic will publish the existing docs/ Markdown tree as a static GitHub Pages site. Markdown stays the only content source; the rendered site is a discoverability and search layer, not a second documentation system.

The generator is exactly pinned Material for MkDocs 9.7.7 with a committed uv lock. Material entered maintenance mode in November 2025: its maintainers committed to critical bug and security fixes for at least 12 months, but no new features. This known support window is acceptable for the v1 launch because the configuration deliberately avoids custom templates and third-party plugins.

Zensical is the planned follow-on. It reads existing mkdocs.yml files and aims to preserve content, URLs, anchors, and Material-compatible customization. Re-evaluate the switch before Material's maintenance commitment ends or earlier if an unfixed security or compatibility issue appears.

2. Contributing to these docs

Run the authoring loop from the repository root:

mise run docs:serve
mise run check:format
mise run check:docs

docs:serve provides the local preview. check:format verifies Markdown and configuration formatting with dprint. check:docs checks the documentation Python formatting and lint, strict types, the documentation unit tests, dependency audit, and docs:build; the build uses the frozen docs/uv.lock, promotes warnings to errors, and writes only to the ignored .agents/tmp/docs-site/ directory. The root check aggregate includes both gates. The site loads no analytics, remote fonts, or custom browser scripts; Material's bundled search and Mermaid support remain local to the generated artifact.

A new or renamed publishable page must appear exactly once in the nav: tree in docs/mkdocs.yml. A direct concept page must also appear exactly once in its owning reserved index: docs/index.md for root pages, or the local index.md under docs/adopters/, docs/adr/, docs/onboarding/, or docs/security/. docs/tests/test_navigation.py and docs/tests/test_indexes.py fail on missing, stale, or duplicate entries, so update navigation and the owning index in the same change as the page.

3. Publication gate

The Docs workflow builds relevant changes on main, but its Pages configuration, artifact upload, and deploy steps remain disabled until the repository variable FGENTIC_PAGES_ENABLED is exactly true. This keeps main green before the repository-level Pages setting exists.

The maintainer performs the publication action under their account:

  1. In Settings → Pages, select GitHub Actions as the source.
  2. Add the repository Actions variable FGENTIC_PAGES_ENABLED=true.
  3. Dispatch the Docs workflow once and verify https://fmind-ai.github.io/fgentic/.
  4. Change the repository homepage from the source-tree URL to the verified Pages URL.

After that one-time gate, every relevant push to main rebuilds and publishes automatically through the protected github-pages environment. Remove or set the variable to any other value to stop publication without changing source or workflow history.