Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-05-16 Updated 2026-05-16

Forge Project Plan 7 — Frontmatter Display

Scope: Override Starlight’s MarkdownContent component to automatically render a styled metadata block from YAML frontmatter fields (status, visibility, owner, etc.) above the page body. Then remove the manually duplicated status table from all document templates, since the component now handles it. Spec: Forge Project Spec Prior plan: Forge Project Plan 6 — Check Revisions

Task 1 — Create MarkdownContent.astro component override

Starlight strips YAML frontmatter from the rendered page. Currently every document template includes a manually-written status table (the “Document Header Convention” from Spec §5) that duplicates the frontmatter values. A custom MarkdownContent component can read frontmatter via Astro.locals.starlightRoute.entry.data and render these fields automatically, eliminating the duplication.

Create .internal/src/components/MarkdownContent.astro:

  1. Import the default Starlight MarkdownContent from @astrojs/starlight/components/MarkdownContent.astro
  2. Read Astro.locals.starlightRoute.entry.data to get frontmatter fields
  3. Render a metadata table above <Default><slot /></Default> with these fields: Status, Visibility, Owner, Approver, Created, Updated
  4. Skip the table entirely if none of these fields are present in the frontmatter (e.g., on pages that don’t use the convention)
  5. Style the table to match Starlight’s design: use the same table styling as the rest of the site, but add a subtle left border or background tint to visually distinguish it as metadata, not body content
  6. The component must work in both light and dark mode (use Starlight CSS custom properties)

Key reference: Astro.locals.starlightRoute.entry.data returns the full frontmatter object including extended schema fields (status, visibility, owner, etc.) as defined in .internal/src/content.config.ts.

Register the override in .internal/astro.config.mjs by adding MarkdownContent to the components object:

components: {
  Pagination: './src/components/Pagination.astro',
  Search: 'starlight-docsearch-typesense/Search.astro',
  MarkdownContent: './src/components/MarkdownContent.astro',
},

Build and verify: cd .internal && npm run build

Task 2 — Remove status table from all document templates

Now that the MarkdownContent override renders frontmatter metadata automatically, the manually-written status tables in the templates are redundant. Remove them to eliminate duplication. The H1 heading remains — only the | Status | Visibility | Owner | Approver | Created | Updated | table and its separator/data rows are removed.

For each template in Forge/Skills/Project_Create/templates/, remove the status table block (3 lines: header, separator, data row) while keeping the H1 heading and everything else intact. The templates to update:

  1. Phase_Template.md — remove the 3-line status table after # {Project} Phase
  2. Requirements_Template.md — remove the 3-line status table after # {Project} Requirements
  3. Research_Template.md — remove the 3-line status table after # {Project} Research
  4. Spec_Template.md — remove the 3-line status table after # {Project} Spec
  5. Plan_Template.md — remove the 3-line status table after # {Project} Plan {N}
  6. State_Template.md — remove the 3-line status table after # {Project} State {N}
  7. Learnings_Template.md — remove the 3-line status table after # {Project} Learnings
  8. WIP_Template.md — remove the 3-line status table after # {Project} WIP

Do NOT remove the Success Criteria table in the Requirements template or any other non-status table.

Task 3 — Remove status tables from existing project documents

The Forge_Project project’s own documents (Requirements, Spec, Plans, States, Phase, etc.) all contain manually-written status tables. Remove them to match the new convention. The frontmatter already contains the same data.

For every .md file in Forge/Projects/Forge_Project/ that contains a status table pattern (a markdown table with Status | Visibility | Owner | Approver | Created | Updated), remove those 3 lines while keeping the H1 heading and all other content intact.

Also scan all other department and project folders for files with the same pattern and remove their status tables. Use: grep -rl "| Status | Visibility | Owner" Forge/ to find all matching files.

Task 4 — Update Spec §5 (Document Header Convention)

Spec §5 currently defines the “Document Header Convention” as a human-readable metadata block below the H1 heading that “makes ownership, status, and navigation visible without reading YAML frontmatter — so it must match it.” With the MarkdownContent override, this is now handled automatically. Update the Spec to reflect the new system.

In Forge_Project_Spec.md, update §5:

  1. Change the section title from “Document Header Convention” to “Frontmatter Display”
  2. Replace the current content with: “Every project document includes YAML frontmatter with the fields Status, Visibility, Owner, Approver, Created, and Updated (in that order). A custom MarkdownContent component override renders these fields as a styled metadata table above the page body automatically. Document authors must NOT duplicate these fields in the body — they are displayed from frontmatter alone.”
  3. Keep the Status values table (draft, review, approved, published, archived) — it’s still needed as a reference
  4. Remove the example markdown block that shows the table in the body

Task 5 — Sidebar registration, build verification, and commit

Standard final task: register new files in sidebar, build, and commit.

  1. Add the MarkdownContent.astro component to the sidebar — this is a source file in .internal/src/components/, not a content doc, so it does NOT need a sidebar entry. Skip this.
  2. Run cd .internal && npm run build to verify the site builds
  3. Commit all changes with message: feat: frontmatter display component + remove manual status tables (Plan 7)