site: support the restructured docs IA, and tune documentation typography - #120
Conversation
✅ Deploy Preview for animated-crumble-fb8862 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Ibrahim2595
changed the title
mrsabath
left a comment
mrsabath
left a comment
There was a problem hiding this comment.
Reviewed both commits, read the full diff, and verified the substantive claims against main and against the Docusaurus 3.10.1 docs. Leaving findings rather than a sign-off, so a maintainer makes the final call — but for what it's worth, I found nothing blocking.
Commit 1 — config/scripts (the required one)
The exclude-replaces-defaults trap is real and correctly fixed. Confirmed against the Docusaurus plugin-content-docs docs: the four default patterns you pasted (**/_*.{js,jsx,ts,tsx,md,mdx}, **/_*/**, **/*.test.{...}, **/__tests__/**) match upstream verbatim and in order, and **/_*/** is indeed what keeps docs/_internal/** out of the build. Repeating them explicitly with the "Do not remove" comment is the right call — this is the kind of thing that silently regresses.
The rest holds up:
sidebars.tsdropping the wrapping category sodocs/index.md(slug: /) owns/docs/— consistent with #2530, and the sidebar stays fully autogenerated.sync-docs.shexcluding_internalfrom the rsync mirror — the versioning rationale (docs:versionsnapshots into a committedversioned_docs/) is the real reason this matters beyond the build exclude, and it's well explained.- The synthesised
docs/index.mdfallback is what makes this safe to merge before #2530, and becomes a no-op after. Good migration hygiene. welcome.mdxCTA repointed to/docs/— valid before and after the restructure.
The merge-order table is correct: this PR first, because #2530-first would briefly expose ~6 internal pages until this exclude lands. Worth honoring.
Commit 2 — typography (CSS only)
Verified against main: the "Before" values are accurate — h1{3rem}, h3–h6{1.5rem} (all identical), .markdown{0.875rem}. And the scoping claim checks out: the base type scale on main is unscoped (h1{}, not .plugin-id-x h1{}), so your .plugin-id-default/.plugin-id-contributing overrides leave the ecosystem landing page's 3rem hero intact. The Netlify deploy preview is green, which is the end-to-end proof.
The new dependency (@fontsource/ibm-plex-mono) is low-risk: same @fontsource scope as the ibm-plex-sans already in the tree, sha512 integrity in the lockfile, official registry, pinned consistently in package.json and package-lock.json.
Two design calls you flagged — noting, not blocking
You called these out yourself, so just acknowledging they're conscious decisions rather than oversights:
- h1 weight 500 vs the llm-d spec's 600 — a deliberate departure from the documented design system. If the team treats the llm-d scale as authoritative, this is the one number to revert; if readability wins, keep it. Either way worth a maintainer's nod since
custom.csscites that system. - 46rem measure (~72ch) — a genuine prose-readability win; the break-out rules for tables/code/diagrams mean it doesn't hurt reference content. Reversible in one line.
Areas reviewed: Docusaurus config, shell (sync-docs.sh), CSS, dependencies/supply-chain, commit/PR conventions.
Commits: 2, both signed off; each independently reviewable as described.
CI: DCO pass, Netlify deploy preview pass.
Clean, careful work — the config trap write-up in particular is exactly the context a reviewer needs.
42dbb14 to
ca34326
Compare
esnible
left a comment
esnible
left a comment
There was a problem hiding this comment.
Summary
Docs-site versioning PR: cuts versioned_docs/version-0.7/ as the released snapshot served at /docs, moves the in-progress docs to /docs/dev, restructures the sidebar to drop a redundant wrapping category, and adds long-form reading typography.
The config work is genuinely well done — deriving the version map from versions.json means cutting 0.8 needs only the snapshot plus that file, with nothing hard-coded in the config. The exclude comment correctly documents the non-obvious Docusaurus behavior that providing exclude replaces the defaults rather than extending them, which is exactly the kind of thing that silently publishes _internal/ notes a year from now if undocumented.
Verified empirically against the deploy preview rather than reasoning from the config alone:
/docs/→ 200, serves "Rossoctl Documentation" (v0.7 generated-index)/docs/dev/→ 200, serves the synthesised index, with the "unreleased documentation" banner rendering/docs/overview/quickstartand/docs/dev/overview/quickstart→ both 200- Version dropdown renders
v0.7 (latest)anddevin the intended order shellcheckclean onsync-docs.sh;set -euo pipefailpresent- New dep
@fontsource/ibm-plex-mono@5.3.0pinned with integrity hash inpackage-lock.json
One note on my own analysis: I initially suspected the v0.7 snapshot was missing an index.md and would 404 at /docs/. That was wrong — versioned_sidebars/version-0.7-sidebars.json retains the wrapping category with slug: '/', so v0.7 gets its root route from the generated index while dev gets it from the synthesised index.md. The two versions use different mechanisms by design, and the preview confirms both resolve.
The 44 snapshot files under versioned_docs/ are mechanical output of docusaurus docs:version and were reviewed as such, not line-by-line.
One thing worth confirming outside this diff: the "MIGRATION WINDOW" branch in sync-docs.sh and the legacy superpowers/** / authbridge/** excludes both exist to tolerate either landing order relative to the upstream rossoctl/rossoctl restructure. Both are well-commented as temporary — if there isn't already a tracking issue to remove them once that lands, they'll quietly outlive their purpose.
Areas reviewed: TypeScript/Docusaurus config, Shell, CSS, JSON, dependency manifests, docs content
Agent/IDE config (.claude/.vscode): none
Commits: 3, all signed-off (DCO passing)
CI status: passing
Two nits inline; neither blocks.
| # matters for versioning: `docusaurus docs:version` snapshots whatever is in | ||
| # docs/ into a COMMITTED versioned_docs/ folder, so without this every release | ||
| # would freeze a copy of those notes into this repo. | ||
| rsync -a --delete --exclude '.DS_Store' --exclude '_internal' "$UP"/ "$DEST"/ |
There was a problem hiding this comment.
nit: --exclude '_internal' is unanchored, so rsync matches that name at any depth — not just the top-level docs/_internal/ the comment describes. This errs in the safe direction (over-excludes rather than under), so no action needed. But if the intent is specifically the top-level notes folder, --exclude '/_internal' states it precisely and won't surprise anyone who later adds a legitimately-published path containing that segment.
There was a problem hiding this comment.
Fixed in d17a136 — changed to --exclude '/_internal'.
You are right that the comment and the code disagreed, and the anchored form is what the comment describes. The unanchored version would also have excluded a legitimately-published .../\_internal/... path if anyone added one later, which is exactly the surprise you are pointing at.
Added a note in the script so the anchor reads as load-bearing:
# '/_internal' is anchored to the top of the transfer, so it excludes exactly
# docs/_internal/ and not a directory of that name at any other depth.Verified after the change: docs/_internal is still absent from the synced tree, and the build produces no route under it.
| // correct whichever order the two PRs land in. --- | ||
| 'superpowers/**', | ||
| 'authbridge/**', | ||
| 'automation-health.md', |
There was a problem hiding this comment.
nit: path: v === LATEST_VERSION ? '' : v reproduces what Docusaurus already does by default for lastVersion — the newest version serves at the bare /docs and older ones under /docs/<version>. Harmless, and being explicit here arguably documents the intended URL shape better than relying on the default. Flagging only so it reads as a deliberate choice rather than a redundancy someone later "cleans up" without realizing it was load-bearing for readers.
There was a problem hiding this comment.
Kept, and documented in d17a136 so it reads as deliberate rather than redundant — which was your ask:
label: v === LATEST_VERSION ? `v${v} (latest)` : `v${v}`,
// Docusaurus already routes the lastVersion at the bare
// /docs and the rest under /docs/<version>. Stating it
// here is deliberate: it documents the URL shape at the
// point a reader looks for it. Keep it.
path: v === LATEST_VERSION ? '' : v,For the record on why I did not drop it: this is the line a reader checks when they want to know where /docs/0.7/ comes from, and relying on the default means that answer lives only in the Docusaurus documentation. llm-d states it explicitly for the same reason.
rossoctl/rossoctl#2530 restructures docs/ into nine task-based sections and moves the team's engineering notes to docs/_internal/. Three things in this repo have to change for that to build, and one landing-page link has to move. 1. docusaurus.config.ts — the docs plugin's `exclude` option REPLACES Docusaurus's defaults rather than extending them, so setting it silently dropped the default '**/_*/**' rule. That rule is what keeps docs/_internal/** out of the build; without it those notes are compiled and the build fails on their repo-relative image links. The defaults are now repeated explicitly, with a comment saying why they must stay. The legacy superpowers/authbridge/automation-health entries are kept so this config is correct whichever order the two PRs land in. 2. sidebars.ts — drop the wrapping "Documentation" category. It added a redundant level above the nine real sections, and its generated-index claimed the /docs/ route that docs/index.md now owns. 3. scripts/sync-docs.sh — exclude _internal from the mirror. Docusaurus would ignore it anyway, but keeping it out of the site tree matters for versioning: `docusaurus docs:version` snapshots whatever is in docs/ into a committed versioned_docs/ folder, so otherwise every release would freeze a copy of the team's plans and retrospectives into this repo. The README slug hack is also removed, since the new tree has no docs/README.md, and a temporary fallback synthesises docs/index.md while upstream has none. 4. ecosystem/welcome.mdx — the "Get started" CTA pointed at /docs/overview/quickstart, which the restructure removes. It now points at /docs/, which is valid before and after the restructure and is itself a router. Verified by running scripts/sync-docs.sh against both the current upstream docs and the restructure branch, then building each. Both orders succeed with zero broken links and zero internal pages published. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
The site-wide type scale is tuned for the landing page, and on a reference page it read as bulky. Two things caused it: - h1 was 3rem against 0.875rem body text — a 3.4x jump — so every heading shouted relative to the prose around it. - h3, h4, h5 and h6 were all 1.5rem, so anything below an h2 had no visible hierarchy. On a page like the CLI reference that flattens the whole structure. This adds a reading scale for documentation pages: body 1rem/1.7, h1 2.25rem, h2 1.5rem, h3 1.1875rem, h4 1rem — a 2.25x jump from body to h1 instead of 3.4x — plus a hairline rule under each h2, which is what makes section boundaries findable while scrolling. Supporting changes, all in the same direction: - IBM Plex Mono for code, self-hosted via @fontsource like the sans already is, so code and prose share one design language. - The first paragraph after the title renders as a standfirst. Every page in the restructured docs opens with a one- or two-sentence orientation, so this is hierarchy from content that already exists. - Line length capped at ~72 characters; tables, code blocks and diagrams break out to the full column width. - Tables get a light header fill, hairline borders and roomier cells, and lose the zebra striping. - Inline code loses its border — a border on every symbol name made reference pages look like forms. - Sidebar section headings and the table of contents become small, quiet, letter-spaced labels. - Body links are underlined. Brand red without an underline reads as emphasis rather than as a link. Scoped to `html.plugin-id-default` and `.plugin-id-contributing`, the classes Docusaurus puts on <html>, so the ecosystem landing page is untouched and keeps its 3rem hero. Stable theme classes and Infima variables only — nothing swizzled, no hashed class names — and both light and dark palettes are defined. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
Two nits from @esnible, neither blocking. - scripts/sync-docs.sh: the rsync exclude was `_internal`, which rsync matches at any depth, not the top-level docs/_internal/ that the comment describes. It is now `/_internal`, anchored to the top of the transfer, so it states what it means and it cannot surprise a later author who adds a published path that contains that word. - docusaurus.config.ts: `path: v === LATEST_VERSION ? '' : v` reproduces the default that Docusaurus already applies to lastVersion. A comment now records that the explicit form is a choice, so nobody removes it as a redundancy. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
ca34326 to
d17a136
Compare
|
Thanks @mrsabath and @esnible. Both nits are addressed in d17a136, and I opened the tracking issue @esnible asked for. The two nits
The temporary shims now have an owner@esnible — you were right that they would quietly outlive their purpose. #123 tracks removing both, blocked on rossoctl/rossoctl#2530:
The issue carries the removal steps, the verification command, and an explicit warning to keep the four Docusaurus defaults in that array — since deleting them is precisely the regression the comment exists to prevent. The two design calls@mrsabath asked for a maintainer's nod on both; @esnible's approval covers them. Recording the state so it is on the record rather than implied:
Both remain one-line reversals if the team's view changes. Rebased onto main#121 merged, so this is now based on @mrsabath — the note that the four default Assisted-By: Claude Code |
Status updateApproved, mergeable, checks green, and rebased onto One thing changed by #121 merging that is worth stating plainly, because it could easily be read the wrong way. This PR still has to merge before rossoctl/rossoctl#2530The three-way stack is gone — both PRs now target #121 did not touch the This PR is what restores that default. Merge it first, and those six pages never reach the site. Merge #2530 first, and six pages of plans, specs and CI reports appear under That is the same trap the Final state
Recorded for the record, not asking for anything@mrsabath flagged two design calls as needing a maintainer's nod, and @esnible's approval covers them. Rather than let that be implied, stating it: h1 weight 500 (a deliberate departure from the llm-d scale that Assisted-By: Claude Code |
github-project-automation
Bot
moved this from New/ToDo
to Done
in Rossoctl Issue Prioritization
4 participants
What & why
Companion to rossoctl/rossoctl#2530, which restructures
docs/into nine task-based sections and moves the team's engineering notes todocs/_internal/.Two commits, reviewable independently:
site: support the restructured docs information architecturesite: tune documentation typography for long-form readingEach is small; the first change below is a genuine trap worth reading.
1.
excludewas silently disabling Docusaurus's own defaultsThe docs plugin's
excludeoption replaces the defaults rather than extending them. Our config set it to hide three internal paths, which quietly dropped the default list — including**/_*/**, the rule that ignores_-prefixed directories.That rule is what keeps
docs/_internal/**out of the build. Without it, those notes get compiled and the build fails on their repo-relative image links.The defaults are now repeated explicitly, with a comment saying why they must stay:
The legacy entries are kept deliberately, so this config is correct whichever order the two PRs land in. Once #2530 merges they are harmless no-ops and can be dropped in a later cleanup.
2.
sidebars.ts— drop the wrapping "Documentation" categoryIt added a redundant level above the nine real sections, and its
generated-indexclaimed the/docs/route thatdocs/index.mdnow owns. The sidebar is still fully autogenerated from the folder tree, so there is nothing to edit here when docs are added or reordered.3.
scripts/sync-docs.sh— keep_internalout of the mirrorDocusaurus would ignore it anyway, but keeping it out of the site tree matters for versioning:
docusaurus docs:versionsnapshots whatever is indocs/into a committedversioned_docs/folder. Without this, every release would freeze a copy of the team's plans, research, and retrospectives into this repo permanently.Also in this file:
docs/README.md, so there is no route collision to work around.docs/index.mdwhen upstream does not provide one. This is what makes this PR safe to merge on its own (see below), and becomes a no-op the moment #2530 lands.4.
ecosystem/welcome.mdx— fix the "Get started" CTAIt pointed at
/docs/overview/quickstart, which the restructure removes. It now points at/docs/, which is valid before and after the restructure, and which the new docs landing page turns into a router with a "Start here" table.Reading typography (second commit, CSS only)
The site-wide type scale is tuned for the landing page. On a long reference page it read as bulky, and two measurements explain why:
3remagainst0.875rembody text — a 3.4x jump, so every heading shouted relative to the prose around it.1.5rem— so anything below an h2 had no visible hierarchy. On a page like the CLI reference that flattens the entire structure.The hairline rule under each h2 is the other half of the fix: it is what makes section boundaries findable while scrolling, instead of a page reading as one continuous block.
Supporting changes, all in the same direction:
@fontsourceexactly as the sans already is, so code and prose share one design language. This is the only new dependency.Scoping and safety
Everything is scoped to
html.plugin-id-defaultand.plugin-id-contributing— the classes Docusaurus puts on<html>— so the ecosystem landing page is untouched and keeps its3remhero. Verified in the built CSS.Stable Docusaurus theme classes and Infima variables only. Nothing swizzled, no hashed class names, and both light and dark palettes are defined.
Two judgement calls to sanity-check
custom.csssays typography follows the llm-d design system, so this is a deliberate departure — it stops large headings from shouting, but it is a design decision, not a fix. One number to revert.max-widthline if the team prefers full width.Merge order
This PR is second of three. It is stacked on #121, so the diff above shows only its own changes. GitHub retargets it to
mainwhen #121 merges..github.githubrossoctldevstarts showing them.Verified with a real build at each step.
v0.7stays frozen at its 27 routes throughout; onlydevchanges.main/docs/mainindex.md_internalno longer matches the oldexcludepatternsThat last row is why the ordering matters: merging the docs PR first would briefly publish
automation-health, an AuthBridge migration guide, and foursuperpowersplans and specs to the live site.How this was validated
Ran this branch's own
scripts/sync-docs.shagainst both docs sources, then built each:Also confirmed that
docs/_internal/,docs/images/, anddocs/diagrams/produce no routes, so images and Mermaid sources do not appear in the sidebar.For the typography commit: every selector was checked against the rendered DOM before being written (
theme-code-block,theme-admonition,theme-doc-sidebar-item-category-level-1,theme-doc-toc-desktop, andheader + pfor the standfirst all exist), the production build carries the rules, the Plex Mono webfiles ship, andh1{font-size:3rem}still applies on the landing page.Not in this PR
Left out to keep this to one purpose:
v0.7, thenv0.8as latest withdevtracking the repo, plus re-enablingdocsVersionDropdown. That should be its own PR after the new IA is live — andv0.7has to be cut from the docs as they are today, before #2530 merges, or the snapshot captures the new structure instead of the old one./docs/*URL moves.@docusaurus/plugin-client-redirectsentries are worth adding so shared links and search rankings survive. Also better as its own PR, alongside versioning.Assisted-By: Claude Code