tools/guitar-prometheus
tools/guitar-prometheus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Strip doxybook2 frontmatter, add doc index #10

Merged
fragmented merged 1 commit from initial-development into mainline 2026-05-28 10:47:18 +00:00
Conversation 0 Commits 1 Files changed 3 +251 -33
fragmented commented 2026-05-28 10:47:13 +00:00
Owner
Copy link

Two new doc-site bugs surfaced once the fragmented-infra docs-builder
ran against the real 350-file doxybook2 output:

  1. Doxybook2 emits its own YAML frontmatter on every page. The
    summary: field often contains a colon-plus-space inside the
    class brief, which YAML interprets as a second mapping entry
    and Astro's docsSchema() then refuses to parse. The previous
    inject script skipped these files because they already had a
    --- open, leaving the broken frontmatter intact — the CI
    build choked on
    bad indentation of a mapping entry at
    classGuitarPrometheus_1_1SongStructure_1_1Score.md:2:34.
  2. None of the staged content is named index.md, so Starlight
    built no root page. / would 404 on the live site.

Inject script:

  • docs-site/scripts/inject-frontmatter.sh: rewritten. If a file
    starts with --- on line 1, find the closing --- line and
    strip the whole block (treats doxybook2's malformed frontmatter
    as throwaway). Falls back to "no frontmatter" semantics when no
    closing fence exists (the leading --- was a markdown HR).
    Then derives title: from the body's first H1 (or a humanised
    basename) and writes a clean ---\ntitle: "X"\n--- block. Pure
    bash, runs unchanged in node:22-slim.

Preview pipeline:

  • scripts/preview-docs-site.sh: also cp documentation/README.md docs-site/src/content/docs/index.md so the docs hub becomes the
    site landing page.

Verified locally: scripts/preview-docs-site.sh now produces a
clean 224-page dist/ — 17 hand-written pages, the new root
index.html, and 206 api-reference pages. Doxygen + doxybook2 are
installed locally so the iteration loop runs against the same
content the CI Docker stage will.

Implementation plan: documentation/agentic-context/
implementation-plans/2026-05-28-docs-site-real-fix-v2.md.

The matching fragmented-infra commit adds the same
README → index.md staging line to the public-sites Dockerfile.

Two new doc-site bugs surfaced once the fragmented-infra docs-builder ran against the real 350-file doxybook2 output: 1. Doxybook2 emits its own YAML frontmatter on every page. The `summary:` field often contains a colon-plus-space inside the class brief, which YAML interprets as a second mapping entry and Astro's docsSchema() then refuses to parse. The previous inject script skipped these files because they already had a `---` open, leaving the broken frontmatter intact — the CI build choked on `bad indentation of a mapping entry` at `classGuitarPrometheus_1_1SongStructure_1_1Score.md:2:34`. 2. None of the staged content is named `index.md`, so Starlight built no root page. `/` would 404 on the live site. Inject script: - docs-site/scripts/inject-frontmatter.sh: rewritten. If a file starts with `---` on line 1, find the closing `---` line and strip the whole block (treats doxybook2's malformed frontmatter as throwaway). Falls back to "no frontmatter" semantics when no closing fence exists (the leading `---` was a markdown HR). Then derives `title:` from the body's first H1 (or a humanised basename) and writes a clean `---\ntitle: "X"\n---` block. Pure bash, runs unchanged in node:22-slim. Preview pipeline: - scripts/preview-docs-site.sh: also `cp documentation/README.md docs-site/src/content/docs/index.md` so the docs hub becomes the site landing page. Verified locally: scripts/preview-docs-site.sh now produces a clean 224-page dist/ — 17 hand-written pages, the new root index.html, and 206 api-reference pages. Doxygen + doxybook2 are installed locally so the iteration loop runs against the same content the CI Docker stage will. Implementation plan: documentation/agentic-context/ implementation-plans/2026-05-28-docs-site-real-fix-v2.md. The matching fragmented-infra commit adds the same README → index.md staging line to the public-sites Dockerfile.
Strip doxybook2 frontmatter, add doc index
All checks were successful
Notify Infra — Rebuild Public Sites / dispatch (push) Successful in 1s
Details
32840bfd76 
Two new doc-site bugs surfaced once the fragmented-infra docs-builder
ran against the real 350-file doxybook2 output:

1. Doxybook2 emits its own YAML frontmatter on every page. The
   `summary:` field often contains a colon-plus-space inside the
   class brief, which YAML interprets as a second mapping entry
   and Astro's docsSchema() then refuses to parse. The previous
   inject script skipped these files because they already had a
   `---` open, leaving the broken frontmatter intact — the CI
   build choked on
   `bad indentation of a mapping entry` at
   `classGuitarPrometheus_1_1SongStructure_1_1Score.md:2:34`.
2. None of the staged content is named `index.md`, so Starlight
   built no root page. `/` would 404 on the live site.

Inject script:
- docs-site/scripts/inject-frontmatter.sh: rewritten. If a file
  starts with `---` on line 1, find the closing `---` line and
  strip the whole block (treats doxybook2's malformed frontmatter
  as throwaway). Falls back to "no frontmatter" semantics when no
  closing fence exists (the leading `---` was a markdown HR).
  Then derives `title:` from the body's first H1 (or a humanised
  basename) and writes a clean `---\ntitle: "X"\n---` block. Pure
  bash, runs unchanged in node:22-slim.

Preview pipeline:
- scripts/preview-docs-site.sh: also `cp documentation/README.md
  docs-site/src/content/docs/index.md` so the docs hub becomes the
  site landing page.

Verified locally: scripts/preview-docs-site.sh now produces a
clean 224-page dist/ — 17 hand-written pages, the new root
index.html, and 206 api-reference pages. Doxygen + doxybook2 are
installed locally so the iteration loop runs against the same
content the CI Docker stage will.

Implementation plan: documentation/agentic-context/
implementation-plans/2026-05-28-docs-site-real-fix-v2.md.

The matching fragmented-infra commit adds the same
README → index.md staging line to the public-sites Dockerfile.
fragmented merged commit 32840bfd76 into mainline 2026-05-28 10:47:18 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
tools/guitar-prometheus!10
No description provided.