Skip to content

Generate AI documentation from existing source at build time - #38

Open
pravijndeca wants to merge 3 commits into
mainfrom
codex/shape-ai-documentation
Open

pravijndeca wants to merge 3 commits into
mainfrom
codex/shape-ai-documentation

Conversation

@pravijndeca

@pravijndeca pravijndeca commented Oct 2, 2026 •

Copy link
Copy Markdown

Generate AI-facing documentation from the existing MDX pages, cards, callouts, and path definitions instead of maintaining a second content source. The manually maintained public/llms.txt is replaced by a build output.

  • Generate a detailed technical index, Markdown versions of all 32 pages, and a combined technical corpus before development and production builds.
  • Extract titles and summaries from the original pages; preserve code blocks, card destinations, and warnings.
  • Keep generated assets and the route manifest out of Git; remove deleted page outputs on regeneration.
  • Advertise the index and per-page Markdown alternatives with appropriate content-type headers.
  • Keep the root shape.network/llms.txt small and route technical queries here; the companion website change generates that index from its homepage and footer.

Validation: seven tests pass, including source-wide code-block preservation, deterministic generation, and generated-link coverage. Next.js compilation, TypeScript checks, and static generation pass with webpack. The build works with generated assets ignored and the manifest loaded at runtime. Formatting and whitespace checks pass.

The default Turbopack compiler stalled locally, so build verification used webpack; the existing default compiler is retained.

@pravijndeca
pravijndeca requested a review from a team as a code owner October 2, 2026 16:10
@vercel

vercel Bot commented Oct 2, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs Ready Ready Preview Oct 31, 2026 11:06pm UTC

Request Review

@pravijndeca pravijndeca changed the title Generate Markdown documentation and AI discovery indexes Generate AI documentation from existing source at build time Oct 2, 2026
- generateMetadata now maps Nextra's metadata.filePath to the generated .md
  path instead of reading the manifest from disk for every page, so pages no
  longer depend on a runtime file read and use paths.canonical for the origin.
- Page summaries in llms.txt come from the lead paragraph, an opening table's
  first column, or section headings, instead of falling back to
  'Documentation for <title>' or a sentence that only introduces a code
  example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017YU1EuhLrUiADjcd88gTCa

This branch was successfully deployed

1 active deployment
Preview — f7c00dd2 Deployed Oct 31, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants