Skip to content

feat: migrate docs from Starlight to Fumadocs at /docs #3

@hey-granth

Description

@hey-granth

Summary

Current documentation is hosted at codectx.granth.tech (root) on an Astro/Starlight template that is outdated, poorly structured, and does not reflect the project's current state (v0.3.0). This issue tracks a full migration to Fumadocs hosted at codectx.granth.tech/docs, freeing the root for the new landing page.

Goals

  • Migrate all existing content from Starlight to Fumadocs
  • Restructure content to reflect the actual pipeline: dependency graph, tier ranking, budget-driven inclusion, AST summaries
  • Make documentation both human-readable and AI-readable
  • Replace template placeholder content with accurate, current information
  • Free codectx.granth.tech/ for the new landing page

Proposed Structure

/docs
├── Getting Started
│   ├── Installation
│   └── Quickstart
├── Concepts
│   ├── How codectx Works
│   ├── Dependency Graph and Context Ordering
│   ├── Tier Ranking
│   └── Budget-Driven File Inclusion
├── Reference
│   ├── CLI Reference
│   └── Configuration
└── Changelog

AI-Friendliness Requirements

  • Add llms.txt at root (codectx.granth.tech/llms.txt) following the llmstxt.org spec
  • Add llms-full.txt: single concatenated plain-text dump of all doc pages, generated at build time
  • All content in MDX/Markdown, no JavaScript-gated rendering
  • Structured headings on every page, no content buried in tabs

Technical Decisions

  • Framework: Fumadocs (Next.js based)
  • Search: Orama (client-side, works with static export)
  • Deployment: Cloudflare Pages, routed under /docs
  • Content source: MDX files under content/docs/

Routing Change

Before After
codectx.granth.tech codectx.granth.tech/docs
codectx.granth.tech/installation codectx.granth.tech/docs/installation
codectx.granth.tech/reference codectx.granth.tech/docs/reference

Redirects from old URLs to new /docs/* equivalents must be configured
at the Cloudflare Pages level to avoid breaking existing links.

Acceptance Criteria

  • All pages from existing Starlight docs migrated with updated content
  • /docs loads Fumadocs shell with working sidebar and search
  • llms.txt present at codectx.granth.tech/llms.txt
  • llms-full.txt generated at build time and accessible
  • Concepts section exists and explains the pipeline accurately
  • CLI Reference documents all flags and options current as of v0.3.0
  • No content references outdated behavior (pre-v0.3.0)
  • Redirects configured from all old root URLs to new /docs/* paths
  • Passes Lighthouse accessibility score >= 90

Out of Scope

  • Landing page (tracked in separate issue)
  • Versioned docs
  • API reference auto-generation

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestfrontend

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions