Skip to content

Groups hexdocs extras by kind of page - #687

Merged
johnnyt merged 1 commit into
mainfrom
sb-agxp-hexdocs-groups-manifest
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
sb-agxp-hexdocs-groups-manifest

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

What changes

  • mix.exs gains groups_for_extras. The one guide hexdocs ships, docs/describing-a-document.md, sits under How-to guides. The README (still main) and the CHANGELOG stay ungrouped at the top. extras and groups_for_modules are unchanged, so the API reference reads as before.
  • No page under docs/adr, docs/plans or docs/spikes is in extras today, and none is added; package.files is unchanged and names nothing under docs/. The README links the decision records by absolute GitHub URL.
  • How-to pages take H1s that start "How to". docs/describing-a-document.md already did; docs/guides/flow-patterns.md, docs/profiles.md and docs/theming.md change their H1 line only. No file is renamed and docs/guides/ keeps its name.
  • .claude/diataxis.md is new: the docs manifest the documentation tools read, generated from the family's manifest table and committed byte for byte as generated. Its example world is patron registration (a visitor becomes a library patron through a few screens).

No file under lib/ changes. No changelog fragment: changelog.d/README.md excludes documentation changes.

Provenance

  • The three H1 changes on pages hexdocs does not ship are this PR's reading of the acceptance's "a how-to page's H1 starts with How to", which does not limit itself to shipped pages; each is a one-line title change and no test reads those titles.
  • Leaving the pages that do not ship today out of extras was decided under the night rule by the conductor, 2026-10-05; the rewritten acceptance on docs/adr was ruled by the operator, 2026-10-05.

Checks

  • mix quality, full profile, green: the Docs stage (mix docs, warnings as errors) and the Doc links stage included.
  • A local mix docs build's sidebar puts the describing-a-document guide under How-to guides and leaves the README and the CHANGELOG ungrouped; the module groups are as on main.
  • The README is unchanged, and the files its links name are neither moved nor renamed.

The one guide hexdocs ships, describing-a-document, now sits under
How-to guides; the README and the CHANGELOG stay ungrouped at the
top, and the module groups are unchanged. Three how-to pages that do
not ship (flow patterns, profiles, theming) take H1s that start
"How to"; no file is renamed. The repository gains .claude/diataxis.md,
the docs manifest the documentation tools read, set in patron
registration.

No file under lib changes.

Refs: sb-agxp
@johnnyt
johnnyt merged commit d820e28 into main Oct 5, 2026
2 checks passed
@johnnyt
johnnyt deleted the sb-agxp-hexdocs-groups-manifest branch October 5, 2026 11:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant