[schmitch]

Fixes #622

What

The README, the guides in docs/ and the changelog become one site at https://forgepkg.github.io/forge/. It has a sidebar in three parts (Running Forge, Formats, CI and publishing), an outline of each page and full-text search. It is built with mdBook 0.5.4.

• docs/SUMMARY.md lists the site's pages in order. The README is the start page and the changelog is the last page. Its links are relative to docs/, so the file also works as a table of contents on GitHub.

• docs/book.toml configures mdBook: the site URL, the GitHub link, light and navy themes, no chapter numbers, and Rust snippets that can't be run.

• cargo xtask docs (xtask/src/docs.rs) stages the pages into target/docs/src, then runs mdbook build into target/docs/book. The pages keep linking each other and the source tree relatively, as GitHub shows them, and the staging rewrites those links:

  • a link to another page goes to that page of the site;
  • a link into the source tree (../crates/…, ../DEVELOPMENT.md, ./LICENSE) goes to the file (blob/main) or directory (tree/main) on GitHub;
  • a link to a missing file or heading fails the build, as does a Markdown file directly in docs/ that SUMMARY.md doesn't list. All problems are reported at once.

  Anchors are made the way GitHub makes them. Links inside code spans and fenced blocks are left alone. The GitHub URL comes from the changelog's [Unreleased]: link, through changelog::repo_url, which is now pub(crate). As in the rest of xtask, there are no new dependencies.

• cargo xtask docs --check runs only the staging and its checks, without mdBook. It is now a step of CI's fmt job. ci-changes.sh adds docs, README.md and CHANGELOG.md to the changelog group, so a docs-only pull request runs fmt and nothing else. A change to the Rust code also runs fmt, which catches a link broken by renaming a file.

• .github/workflows/pages.yml builds the site and deploys it:

  • on pushes to main that change a page, and on demand;
  • for pull requests that change how the site is built (book.toml, SUMMARY.md, docs.rs, the workflow), it only builds;
  • it uses actions/upload-pages-artifact v5.0.0 and actions/deploy-pages v5.0.1, pinned by commit SHA like every action here, both released more than six weeks ago. mdBook comes from the already-pinned taiki-e/install-action, whose manifest has 0.5.4.

• Docs: DEVELOPMENT.md gets a Documentation site section and a line in the helper-command list, the xtask help text has the new command, and the README links the site.

Before it can deploy

A repository administrator must set Settings → Pages → Source: GitHub Actions once; no tool available to this session can change that setting. Until then the deploy job fails, and the first push to main after the setting deploys the site. Re-run all jobs on the workflow's last run deploys it right away.

How it was checked

• cargo test -p xtask: 31 + 1 tests pass, including six new ones (anchor names, repeated headings, code left alone, the staging of a small repository, every kind of broken link, path resolution). cargo fmt --all --check and cargo clippy -p xtask --all-targets -- -D warnings are clean.
• cargo xtask docs --check on the real pages: all 12 pages, every link resolves. cargo xtask changelog --check and image-pin-check.sh pass, and both workflows parse.
• Built with mdBook 0.5.4. Every one of the 137 links between pages in the HTML reaches a page and an id, so mdBook names headings the way GitHub does. No .md link is left over, and 145 links go to GitHub. Screenshots of the start page, a guide and a search came out as expected.
• ci-changes.sh was tested on a probe commit that touches only docs/gitlab-ci.md: changelog=true, every other group false.

Not in this PR

mdBook warns about five placeholders written as raw tags: **Admin → Users → <user>** and the like, in docs/deployment.md (3) and CHANGELOG.md (2). GitHub drops those tags as well, so the text already reads "Admin → Users →" today. Escaping them is a separate fix, and CHANGELOG.md is not edited by changes.

Changelog

docs/changes/2.1.1/622.docs.md, next to #618's fragment, under 2.1.1 for the same reason (there is no milestone for the next release yet).

---

Generated by Claude Code