feat(docs): migrate component documentation to Fumadocs MDX#20
Merged
Conversation
Phase 1 of Fumadocs migration: - Move entire app into apps/docs/ - Add Turborepo config with dev/build/lint tasks - Add packages/config with shared tsconfig.base.json - Add pnpm workspace config - Create root package.json with workspace scripts - Rename docs package to @jalco/docs - Update husky for monorepo paths - Verify build passes from new location
Phase 2 of migration: - Install fumadocs-core 16.6, fumadocs-mdx 14.2, fumadocs-ui (base-ui 16.6) - Upgrade to Next.js 16.2, React 19.2, Zod 4 - Add source.config.ts for MDX collection definition - Add lib/source.ts with Fumadocs page source loader - Add mdx-components.tsx with Fumadocs defaults - Wire createMDX into next.config.ts - Create content/docs/ with meta.json sidebar ordering for all 28 components - Create initial MDX pages: index.mdx, components/index.mdx - Add fumadocs-mdx:collections path mapping to tsconfig - Exclude .source/ from ESLint, suppress ignored-file warnings in lint-staged - All 42 existing pages still build alongside Fumadocs
Phase 3: registry index for Fumadocs ComponentPreview, getRegistryComponent helper, build pipeline wiring. Registry stays at registry/ — zero breakage.
Add app/docs/[...slug]/page.tsx that renders MDX content from content/docs/ via Fumadocs. Explicit TSX pages take priority — the catch-all only serves pages without a TSX counterpart. This enables gradual migration: delete a TSX page, create the MDX, and it works automatically.
Sitemap now merges routes from both the existing nav structure and Fumadocs page source, deduplicating. As TSX pages are migrated to MDX, the sitemap stays complete automatically.
Initialize package manager state with server-safe default, then sync from localStorage in useEffect. The previous useState initializer read localStorage during SSR which caused hydration mismatches with React 19.2 / Next 16.
Prove the Fumadocs MDX pipeline end-to-end: - ComponentPreview + ComponentPreviewClient for rendering in MDX - InstallBlock wrapping existing InstallCommand - Example components in registry/status-indicator/examples/ - Auto-discover examples in build-registry-index script - status-indicator.mdx replaces the TSX page - All 42 pages build successfully
…status-indicator MDX - Register all 28 registry components + docs infrastructure as MDX components - Rewrite status-indicator.mdx to use ComponentDocsPage, VariantGrid, CodeLine, ApiRefTable — identical quality to the old TSX page - Fix export names: StepperItem, LogViewerTerminal/Minimal/Filterable, TipJar variants - Pattern proven: MDX pages can use the full docs component system with zero quality loss
Establish the correct MDX pattern: - Example files in registry/<name>/examples/ for each preview - Clean MDX with ComponentPreview, markdown code blocks, ApiRefTable - No template literals or TypeScript in MDX body - status-indicator, commit-graph, color-palette all working as MDX - 25 TSX pages remaining to convert
…tte to MDX 4 components fully converted with example files + clean MDX. 24 TSX pages remaining.
All TSX component docs pages are now MDX files in content/docs/components/. Each uses ComponentPreview with the existing preview files — no new example files needed for most components. Detailed examples exist for status-indicator, commit-graph, color-palette, testimonial, and logo-cloud. - 28 MDX files in content/docs/components/ - 0 TSX component pages remaining - Registry index auto-discovers preview files as ComponentPreview targets - All 41 pages build successfully - Playground files restored to components/docs/playgrounds/
Replace the static lib/docs.ts sidebar with a Fumadocs-powered sidebar that reads from the auto-generated page tree (MDX files + meta.json). Keeps the existing visual design — spring animation, scroll indicator, New badges from latest release. The sidebar now auto-discovers pages from content/docs/ without manual nav configuration.
Create example files and full MDX docs for: - color-palette (grid + scale demos) - license-badge (layouts + categories demos) - repo-card (single + grid demos) - contributor-grid (grid + list demo) All 8 batch 1 components now have proper MDX pages with ComponentPreview demos, API reference tables, and notes. 42 pages building successfully.
The MDX ComponentPreview now wraps the real ComponentPreview server component which renders the tabbed Preview + Code panels with syntax-highlighted source files. Previously it was a stripped-down version showing only the live component with no code tab.
The catch-all page now detects component pages and renders: - CopyPromptButton with the full AI-friendly component prompt - AiCopyButton with page summary for copying to AI destinations - DependencyBadges showing npm and registry dependencies These match the original ComponentDocsPage header behavior.
- Fix 13 auto-generated MDX pages that showed ApiRefTable instead of the actual component name in import/usage examples - Reduce MDX content gap from gap-12 to gap-8 for tighter layout
…onent names Sidebar: - Add Getting Started section with Components, Installation, Color Themes, Releases as static links above the Fumadocs page tree - All pages now accessible from the sidebar Code blocks: - Replace all markdown triple-backtick blocks with CodeLine components across 27 MDX files so they use the registry's syntax highlighting Component names: - Fix 13 auto-generated pages that showed wrong component names (ApiRefTable instead of the actual component) in usage examples Cleanup: - Rename changelog route to releases - Tighten MDX content spacing (gap-12 → gap-8)
Extract ApiRefTable blocks and Notes sections from old TSX pages (recovered from git history) and append to all stub MDX pages. Every component page now has: - ComponentPreview with tabbed Preview/Code view - InstallBlock with package manager tabs - CodeLine usage examples - API Reference table(s) with all props - Notes section with component-specific details 19 pages enriched automatically + 1 manually (api-ref-table). 8 batch-1 pages were already rich.
…arators, tighten spacing - Remove index.mdx from root meta so 'Introduction' doesn't show as a separate sidebar item - Remove components/index from components meta (covered by static link) - Flatten the Components folder into the sidebar so category separators (Code, Docs, Open Source, etc.) render directly - Tighten sidebar gap from gap-6 to gap-1 with pt-5 on separators for clear visual grouping without excess whitespace - Add pb-2 to Getting Started section for separation
Kbd: - Add Variants, Sizes, Examples, Color Schemes sections - Import VariantGrid and registry components Stepper: - Add Examples section with status indicators, rich content, horizontal orientation, and custom icons AGENTS.md: - Document Fumadocs MDX docs workflow - Require restoring showcase depth, not just structure - Require Fumadocs page tree for sidebar changes
…viewer, request-viewer File Tree: - Add Examples section with icon styles, highlighted files, expand state - Import FileTree and define sample tree data JSON Viewer: - Add Examples section with expanded depth and package manifest configs - Import JsonViewer and define sample JSON data Log Viewer: - Add Variants section with Terminal, Filterable, and Minimal variants - Import LogViewer components and define sample logs Request Viewer: - Add Examples section with GET and POST request samples - Import RequestViewer and define network request data
…roducthunt, tip-jar
…jar, cron, diff, ai-copy, json, log, request, activity
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR migrates the entire documentation system from custom TSX-based route pages to a unified Fumadocs MDX infrastructure. It establishes a scalable monorepo structure and ensures full feature parity for all 28 existing components.
Key Changes
CodeBlockCommandand corrected script console errors.Checklist
AGENTS.mdpnpm buildpassesNotes