Skip to content

Groups hexdocs pages by kind and adds a manifest - #129

Merged
johnnyt merged 1 commit into
mainfrom
ece-2fk9-hexdocs-groups-manifest
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
ece-2fk9-hexdocs-groups-manifest

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

What changes

The hexdocs sidebar groups each shipped page by the kind of page it is,
in the family order, where one "Guides" group held them all:

  • How-to guides: the pages under docs/guides/.
  • Explanation: docs/explanation/moving-off-cloak.md.

The README (still main) and the CHANGELOG stay ungrouped at the top.
The extras list, the package files and the API reference do not change;
no decision record, plan or other contributor path was ever an extra
here, and none is added.

Two how-to pages take "How to" titles; their files keep their names and
docs/guides/ keeps its name:

  • two-vaults-customer-and-agreement.md: "How to keep a customer scope
    and an agreement scope in two vaults".
  • scope-in-jobs-and-projectors.md: "How to resolve the scope in jobs
    and projectors".

The link text for those two pages in README.md and docs/README.md
follows the new titles; every link target is unchanged. The two guide
tests read only the pages' code blocks, so the titles do not reach them.

.claude/diataxis.md is new: the docs manifest the documentation tools
read (audience, where each kind of page lives, the contributor paths,
the executed snippets). Examples in this package are domain-free. It is
the generated file, byte for byte; neither prose line was changed.

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

Checks

  • Full mix quality green on the committed tree, including the Docs
    stage (ExDoc warnings as errors) and the doc_links stage.
  • The built sidebar was read back: README, Changelog and API Reference
    ungrouped; every docs/guides/ page under "How-to guides"; the
    explanation page under "Explanation".

Review

Gate tier, the worker's own review round: docs configuration under the
size threshold, no contract surface.

The hexdocs sidebar groups the shipped pages under "How-to guides"
(docs/guides/) and "Explanation" (docs/explanation/) where one
"Guides" group held them all. The README and the CHANGELOG stay
ungrouped at the top, main stays the README, and the API reference
and package files do not change.

Two how-to pages take "How to" titles: the two-vaults page and the
scope-in-jobs page. Their files keep their names, and the link text
in README.md and docs/README.md follows the new titles.

Adds .claude/diataxis.md, the docs manifest the documentation tools
read: where each kind of page lives, the audience, and that examples
here are domain-free.

Refs: ece-2fk9
@johnnyt
johnnyt merged commit 28c317f into main Oct 5, 2026
1 check passed
@johnnyt
johnnyt deleted the ece-2fk9-hexdocs-groups-manifest branch October 5, 2026 11:19
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