Fix body links + group sidebar by audience #11
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "initial-development"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Last round shipped a buildable docs site but the rendered pages had
two usability problems: body-content
.mdlinks 404'd, and thesidebar drowned customer-facing content in deep developer material.
Body-content link rewriting:
.mdlink targets inthe auto-generated sidebar nav; inside plain
.mdbody content,[Getting Started](getting-started.md)rendered as a raw<a href="getting-started.md">and click-through 404'd.Doxybook2's API-reference cross-refs had a related problem —
they're emitted as site-root-absolute URLs like
/Classes/struct_foo.mdand never picked up the/api-reference/prefix.after frontmatter injection. Walks the staged content tree and
rewrites every
[text](url)whose target is a.mdpath,relative or site-root absolute. Resolves the target against the
file's directory, lowercases every path segment to match
Starlight's slug rule, strips
.md, and writes back as anabsolute URL with a trailing slash. Anchors are preserved
(
foo.md#bar->/.../foo/#bar). External URLs, anchor-onlylinks, and non-.md targets are left alone.
baseUrlfrom/to/api-reference/so its cross-refs carrythe section prefix natively. Slug casing still doesn't match
Starlight's lowercased output, but the rewriter normalises that.
frontmatter inject step. Matching fragmented-infra commit
("Run docs link rewriter in docs-builder stage") adds the same
RUN line to the public-sites Docker stage.
Sidebar grouping:
groups. User Guide stays flat and expanded so the four customer
pages are immediately visible. Developer Reference is collapsed
by default and holds Architecture / Development / API Reference
as nested subgroups. Previously all four groups sat side-by-side
at the top level, and 350+ API-reference entries dominated the
scroll.
Generated artefact:
build-api-docs.sh run (the script always writes the section
README from a heredoc). Net of editorial drift this round.
Verified locally: scripts/preview-docs-site.sh produces 224 pages
in dist/. Body links resolve correctly
(
/customer/getting-started/,/api-reference/classes/.../#variable-velocityboost). Sidebarshows two top-level groups with the expected nesting.
Last round shipped a buildable docs site but the rendered pages had two usability problems: body-content `.md` links 404'd, and the sidebar drowned customer-facing content in deep developer material. Body-content link rewriting: - Astro / Starlight 0.30 only auto-rewrites `.md` link targets in the auto-generated sidebar nav; inside plain `.md` body content, `[Getting Started](getting-started.md)` rendered as a raw `<a href="getting-started.md">` and click-through 404'd. Doxybook2's API-reference cross-refs had a related problem — they're emitted as site-root-absolute URLs like `/Classes/struct_foo.md` and never picked up the `/api-reference/` prefix. - New docs-site/scripts/rewrite-md-links.mjs: Node script run after frontmatter injection. Walks the staged content tree and rewrites every `[text](url)` whose target is a `.md` path, relative or site-root absolute. Resolves the target against the file's directory, lowercases every path segment to match Starlight's slug rule, strips `.md`, and writes back as an absolute URL with a trailing slash. Anchors are preserved (`foo.md#bar` -> `/.../foo/#bar`). External URLs, anchor-only links, and non-.md targets are left alone. - documentation/scripts/build-api-docs.sh: switch doxybook2 `baseUrl` from `/` to `/api-reference/` so its cross-refs carry the section prefix natively. Slug casing still doesn't match Starlight's lowercased output, but the rewriter normalises that. - scripts/preview-docs-site.sh: invoke the rewriter after the frontmatter inject step. Matching fragmented-infra commit ("Run docs link rewriter in docs-builder stage") adds the same RUN line to the public-sites Docker stage. Sidebar grouping: - docs-site/astro.config.mjs: restructure into two top-level groups. User Guide stays flat and expanded so the four customer pages are immediately visible. Developer Reference is collapsed by default and holds Architecture / Development / API Reference as nested subgroups. Previously all four groups sat side-by-side at the top level, and 350+ API-reference entries dominated the scroll. Generated artefact: - documentation/api-reference/README.md: regenerated by the latest build-api-docs.sh run (the script always writes the section README from a heredoc). Net of editorial drift this round. Verified locally: scripts/preview-docs-site.sh produces 224 pages in dist/. Body links resolve correctly (`/customer/getting-started/`, `/api-reference/classes/.../#variable-velocityboost`). Sidebar shows two top-level groups with the expected nesting.