Implement sidebar and page meta controls

[will-lamerton]

Summary

Currently, page titles in the documentation are auto-generated from filenames, and pages appear in the sidebar in whatever order the file system provides. This issue requests implementing proper metadata controls via YAML frontmatter or _meta.json files.

Problem Description

• Page titles are auto-generated from filenames via pathToDisplayName() in page-map-builder.ts (e.g., getting-started.md → "Getting Started")
• No control over page ordering in the sidebar
• No way to add page descriptions for SEO
• Cannot group pages into custom sections
• extractTitle() in remote-content.ts already parses frontmatter titles for the page's <title> tag, but buildPageMapForVersion() ignores this and uses filename-based titles for the sidebar

Important: Remote Content Architecture

This site fetches docs remotely from GitHub at build time — it does not use Nextra's filesystem-based routing. The page map is built manually in lib/page-map-builder.ts by calling getAllDocsFiles() from lib/github.ts, which fetches directory listings via the GitHub API.

This means:

• Nextra's native _meta.json support will not work — it relies on filesystem-based routing which this site bypasses
• Any _meta.json support must be custom implemented: fetched from the remote repos and parsed in page-map-builder.ts
• Frontmatter is the lower-effort approach since extractTitle() already demonstrates frontmatter parsing, and the content is already fetched for each page

Proposed Solution

Approach 1: YAML Frontmatter (Recommended)

Extend the existing frontmatter parsing in remote-content.ts and wire it into buildPageMapForVersion():

---
title: "Custom Page Title"
description: "Page description for SEO"
sidebar_order: 1
hidden: true
---

Implementation:

1. In buildPageMapForVersion(), fetch each file's content (or at minimum its first ~50 lines) to extract frontmatter
2. Use parsed title instead of pathToDisplayName() for sidebar labels
3. Sort page map entries by sidebar_order before returning
4. Filter out entries with hidden: true from the page map

Trade-off: This requires fetching file content during page map building (currently only file paths are fetched). This adds API calls but can be mitigated with caching.

Approach 2: Remote _meta.json Files

Fetch and parse _meta.json files from each remote repo's docs/ directory:

{
  "getting-started": {
    "title": "Getting Started",
    "description": "Learn how to set up...",
    "order": 1
  },
  "api-reference": {
    "title": "API Reference",
    "order": 2
  }
}

Implementation:

1. Update getAllDocsFiles() in github.ts to also return _meta.json files (currently only .md/.mdx are collected)
2. In buildPageMapForVersion(), check for _meta.json in each directory and fetch its content
3. Apply titles, ordering, and other metadata from _meta.json to the generated PageMapItem[]

Trade-off: Requires doc authors in each project repo to maintain _meta.json files alongside their markdown. More powerful but higher maintenance.

Requirements

1. Title override - Allow custom titles instead of auto-generated ones
2. Page ordering - Support numeric ordering in sidebar
3. Descriptions - Extract descriptions for SEO meta tags
4. Hidden pages - Option to hide pages from sidebar but keep them accessible
5. Grouping - Support custom section headers in sidebar

Files Likely Affected

• lib/page-map-builder.ts - Core changes: parse frontmatter/meta and apply to PageMapItem[] entries
• lib/github.ts - If using _meta.json approach: update getAllDocsFiles() to also fetch _meta.json
• lib/remote-content.ts - Extend extractTitle() to extract additional frontmatter fields (order, description, hidden)
• app/[project]/docs/[version]/[[...slug]]/page.tsx - Pass description metadata for SEO

Success Criteria

• Pages can specify custom titles via frontmatter (or _meta.json)
• Sidebar respects ordering field for sorting
• Descriptions are available for SEO
• Hidden pages don't appear in sidebar navigation
• Works within the remote content fetching pipeline (no reliance on local filesystem)

Additional Notes

• This also unlocks proper SEO optimization for the documentation pages
• Approach 1 (frontmatter) is recommended as the starting point since the infrastructure already exists in extractTitle()
• Approach 2 (_meta.json) can be layered on later for more granular control