Pular para conteúdo

AUR-560: documentation site (MkDocs Material, container, GitHub Pages)

Design

  • mkdocs.yml (root): docs_dir: docs, Material theme in pt-BR, navigation.tabs, navigation.indexes, navigation.top, search.suggest, search.highlight, content.code.copy, plugin search with lang: [pt] (static index, works offline), strict: true and link/anchor validation at warn level so --strict fails on a broken link, a page missing from the nav or a missing anchor. The nav is explicit and grouped by capability: Inicio, Comecando, Referencia, Guia corporativo, Qualidade e benchmark and Specs. There is no extra plugin, so the image alone builds the site.
  • Home page is docs/index.md: product overview with one section per capability, each linking its reference anchor in configuration.md and naming its tutorial. A tutorial that does not exist yet is cited as em breve (AUR-56x,tutorials/.md) without a link, so --strict stays green; AC-004 requires the link as soon as the file exists.
  • docs/README.md stays the repository entry point. MkDocs drops README.md when index.md exists (and the specs link ../README.md), so scripts/docs/hooks.py re-adds it as its own page at /README/ (exclude_docs lists /README.md only to silence the conflict warning). docs/site/ (the older hand-written interactive guide, published by pages.yml) is excluded except workflow.yml, which getting-started.md links.
  • scripts/docs/build.sh runs docker run ... <image@digest> build --strict; scripts/docs/serve.sh serves locally. Both read the single line of scripts/docs/image.lock, which the workflow reaches by calling build.sh. The Specs section (and Tutoriais when docs/tutorials exists) is not in mkdocs.yml: scripts/docs/hooks.py on_config injects it before page validation (specs/README.md, then specs/AUR-*.md in natural order; for tutorials tutorials/README.md, then tutorials/*.md). Nothing to maintain by hand; AC-002 reimplements the rule in bash and fails on any orphan page.
  • .github/workflows/docs.yml: push to main (paths docs/**, mkdocs.yml, scripts/docs/**, the workflow) and workflow_dispatch. Job build runs scripts/docs/build.sh (same image, --strict) and uploads site/; job deploy (needs: build, environment github-pages) is the only one with pages: write and id-token: write.

Pinned image

squidfunk/mkdocs-material@sha256:51b87149d227691486b5f08993d28c65ca7e4990010664b697265b8e6fcd5287

Tag squidfunk/mkdocs-material:9.7.7 (MkDocs 1.6.1, Material 9.7.7), digest resolved with docker pull and docker inspect --format '{{index .RepoDigests 0}}' on 2026-10-02. Nothing is installed on the host.

Actions (SHA of the tag commit, confirmed with gh api repos/<owner>/<repo>/git/ref/tags/<tag>)

Action Tag SHA
actions/checkout v7.0.1 3d3c42e5aac5ba805825da76410c181273ba90b1
actions/configure-pages v6.0.0 45bfe0192ca1faeb007ade9deae92b16b8254a0d
actions/upload-pages-artifact v5.0.0 fc324d3547104276b827a68afc52ff2a11cc49c9
actions/deploy-pages v5.0.1 368f82528645a54fb793d4d04e342629a3f51346

Real build (outside the sandbox)

scripts/docs/build.sh from the card branch, exit code 0, complete output (no WARNING; the Material banner about MkDocs 2.0 is silenced with NO_MKDOCS_2_WARNING=true in the scripts):

```text build-strict-log INFO - Cleaning site directory INFO - Building documentation to directory: /docs/site INFO - Documentation built in 3.03 seconds 

search_index_sha256: 3adb201c49b3eabf3b7f56d64d825906d2a9d7d226100d224d88fb9eddcb9bb2
search_index_docs: 1265

The hash is of `site/search/search_index.json` from the build made just before
this file recorded it (this page is itself indexed, so the recorded value
cannot include its own text); AC-001 checks the shape, not equality.

## Serving locally

```bash
scripts/docs/serve.sh   # http://127.0.0.1:8000, needs only Docker
scripts/docs/build.sh   # writes ./site (git-ignored through .git/info/exclude)

Adding tutorials (AUR-561..564)

Each tutorial card creates docs/tutorials/<name>.md (and optionally docs/tutorials/README.md as the section index); the hook adds the Tutoriais tab by itself, no mkdocs.yml edit. Then replace the em breve (AUR-56x, ...) text in docs/index.md by a link to the file. AC-002 fails on a tutorial that is not in the nav and AC-004 fails on a tutorial that exists but is not linked from the index. docs/tutorials does not exist yet, so the Tutoriais tab does not appear yet.

Legacy Pages workflow removed

.github/workflows/pages.yml is deleted: two workflows deploying to the same github-pages environment overwrite each other, so docs.yml is the only publisher. The hand-written guide in docs/site/ stays in the repository as an archive (its workflow.yml is still served by the site, linked from getting-started.md); it is no longer published on its own. AC-003 requires exactly one workflow using actions/deploy-pages.

Outside this card's paths: docs/qa.md line 19 still says publication uses pages.yml; it needs a one-line fix by whoever owns that page.