Skip to content

Docs site policy

How the docs/ tree gets published as a browsable website, the custom-domain plan, and the release-time freshness gate.

The site

Property Value
Generator MkDocs
Theme Material for MkDocs
Source docs/ tree + mkdocs.yml at repo root
Build .github/workflows/docs.yml — fires on push to main touching docs/** or mkdocs.yml
Deploy target GitHub Pages, environment github-pages
Default URL https://nollagluiz.github.io/AI_forSE/
Custom domain docs.tlsstress.art (per docs/CNAME) — DNS provisioning pending
Strict mode mkdocs build --strict — broken intra-doc anchors fail the build

Custom domain setup

The docs/CNAME file declares the custom domain GitHub Pages should serve. When the brand domain is registered with a CNAME record pointing at nollagluiz.github.io, GitHub Pages will auto-provision HTTPS via Let's Encrypt.

DNS configuration required (when ready):

docs.tlsstress.art.    CNAME    nollagluiz.github.io.

After the DNS record propagates:

  1. GitHub repo → Settings → Pages → confirm "Enforce HTTPS"
  2. Wait ~10 minutes for Let's Encrypt provisioning
  3. Verify with curl -I https://docs.tlsstress.art/ — expect 301 to https://docs.tlsstress.art/ (canonical) then 200

The DNS step is the only manual gate; everything else is codified in docs/CNAME + the workflow.

What the site renders

The nav in mkdocs.yml is the authoritative table of contents. It groups docs into:

  • Home — README equivalent in 3 languages (en / pt-BR / es)
  • Architecture — canonical scope reference
  • Getting started — 12 quickstart guides (4 modes × 3 languages)
  • DUT / NGFW — testbed operations + NGFW vendor configs
  • Security — ZTP-prem posture + operator guide + compliance mappings
  • Operations — performance tuning + sustainability + NetSecOPEN
  • Help Center — 20 engine + module primers
  • Governance — RFC / Deprecation / Release / Backport / Quality / VEX / License / Audit-trail / this doc
  • Runbooks — DR drill, chaos, compliance, verify-release
  • ADRs — 33 architecture decision records

Each section's deepest leaf opens with a back-link to its section's index page; readers can browse depth-first or breadth-first.

Release-time freshness gate

The mkdocs build --strict step in docs.yml is the gate. It catches:

  • Broken intra-doc anchors (heading drift)
  • Missing files referenced by nav
  • Plugins not installed
  • Theme errors

Mkdocs validation settings downgrade three specific link classes from "warning" to "info":

  • not_found — many docs link to files outside the rendered site (e.g. ../scripts/foo.sh) that render correctly on github.com but mkdocs can't resolve in the Pages site
  • absolute_links — same rationale
  • anchors — slugifier inconsistency across trilingual heading variants (Unicode accent handling)

The scripts/docs-link-audit.py script (G9-followup, run before tagging) catches the github.com broken-link case that mkdocs ignores. Belt + braces.

How to add a new doc

  1. Write the doc under docs/ (must follow the same ## Section / ### Subsection heading hygiene as existing docs; mkdocs slugifies these for anchor refs)
  2. Add an entry to nav: in mkdocs.yml (this is what creates the site-side navigation)
  3. The docs.yml workflow rebuilds and redeploys automatically on next push to main
  4. Verify the new doc renders at the published URL

If the doc is bilingual or trilingual, follow the existing pattern: separate file per language with .pt-BR.md / .es.md suffix, all three listed under the same nav parent.

When the docs site goes down

  • The github.com README + the per-folder READMEs continue to work — they're rendered server-side by GitHub, not by our Pages deployment
  • Most users land at github.com first anyway; the Pages site is the searchable + cross-linkable navigator

So a Pages outage doesn't take down documentation; it removes the unified-navigation surface only.

Why this matters

For audit / valuation, a published documentation site is a maturity signal: it says "we render our docs, we keep them parseable, we publish a versioned navigation". A scattered docs/ tree on github.com works but feels solo-project.

For procurement, the published site is the canonical shareable URL. Investors and customers can bookmark docs.tlsstress.art without needing GitHub credentials. The README badges become entry points to specific pages on the canonical domain.

  • Quality gates — release-prep checklist includes the docs build
  • Release cadence — docs deploy is push-on-merge, no version coupling
  • .github/workflows/docs.yml — the build + deploy workflow
  • mkdocs.yml — site config + nav source of truth
  • docs/CNAME — custom domain declaration

Last verified against shipping code: v3.7.0 (2026-05-12).