Skip to Content
GuidesDocumentation

Documentation System

This project uses Nextra to power the /docs experience with MDX content and the docs theme.

Features

📚 MDX-Based Content

Write documentation in MDX (Markdown + JSX) with support for:

  • Rich markdown syntax with GitHub Flavored Markdown (GFM)
  • React components embedded directly in your docs
  • Code syntax highlighting with Shiki
  • Frontmatter metadata for titles, descriptions, and more

🎨 Beautiful UI

Built with Nextra theme:

  • Responsive sidebar navigation with collapsible sections
  • Table of contents for easy navigation within pages
  • Previous/Next navigation between pages
  • Full-text search functionality
  • Clean, professional design

🚀 Developer Experience

Optimized for productivity:

  • Hot reload - see changes instantly during development
  • Type-safe - full TypeScript support
  • Fast builds - optimized for Cloudflare Workers with OpenNext
  • Git-based - version control your docs alongside code

Directory Structure

Documentation content is organized in the src/app/docs/ directory:

src/app/docs/
├── layout.tsx             # Nextra docs shell
├── page.mdx               # Documentation home page
├── _meta.js               # Root navigation configuration
├── getting-started/
│   ├── _meta.js           # Section navigation
│   ├── installation/
│   │   └── page.mdx
│   ├── configuration/
│   │   └── page.mdx
│   └── deployment/
│       └── page.mdx
└── guides/
    ├── _meta.js
    ├── authentication/
    │   └── page.mdx
    ├── blog-system/
    │   └── page.mdx
    └── documentation/
        └── page.mdx

Keep this tree user-facing. Internal contributor guidance should live in .pm/docs/knowledge/ or in route-local AGENTS.md files, not inside published page.mdx content.

Creating Documentation

Add a New Page

  1. Create a new folder and page.mdx file in the appropriate directory:
mkdir -p src/app/docs/guides/my-guide
touch src/app/docs/guides/my-guide/page.mdx
  1. Add frontmatter and content:
---
title: My Guide
description: A helpful guide about something
---
 
# My Guide
 
Your content here with **markdown** formatting!
 
## Sections
 
Use headers to organize your content.
  1. Update the _meta.js file in the parent directory:
export default {
  authentication: "Authentication",
  "blog-system": "Blog System",
  "my-guide": "My Guide",
};

Add a New Section

  1. Create a new directory:
mkdir -p src/app/docs/my-section/page-1
mkdir -p src/app/docs/my-section/page-2
  1. Create _meta.js for navigation:
export default {
  "page-1": "Page 1",
  "page-2": "Page 2",
};
  1. Add pages to the section:
touch src/app/docs/my-section/page-1/page.mdx
touch src/app/docs/my-section/page-2/page.mdx

Frontmatter Options

Each MDX file should include frontmatter at the top:

---
title: Page Title
description: Brief description for SEO and previews
---

Available Fields

  • title (required) - Page title shown in navigation and header
  • description (optional) - Meta description for SEO

Markdown Features

Code Blocks

With syntax highlighting:

```tsx
import { Button } from "~/components/ui/button";
 
export function Example() {
  return <Button>Click me</Button>;
}
```

Link to other documentation pages:

See also: [Authentication Guide](/docs/guides/authentication)

Tables

Create data tables:

| Feature | Description         |
| ------- | ------------------- |
| MDX     | Markdown with JSX   |
| Search  | Full-text search    |
| Theme   | Customizable design |

Lists

Ordered and unordered lists:

- Item 1
- Item 2
  - Nested item
  - Another nested item
 
1. First step
2. Second step
3. Third step

Images

Add images to your docs:

![Alt text](/images/screenshot.png)

Blockquotes

Highlight important information:

> **Note:** This is an important note that readers should pay attention to.

Configuration

Customize Theme

Edit theme.config.tsx in the project root:

import { Footer, Navbar } from "nextra-theme-docs";
 
const docsThemeConfig = {
  navbar: (
    <Navbar
      logo={<span>Your Docs Logo</span>}
      logoLink="/docs"
      projectLink="https://github.com/aigotowork/cfstack"
    />
  ),
  footer: <Footer>Your Footer Text</Footer>,
  docsRepositoryBase: "https://github.com/aigotowork/cfstack/tree/main/src/app",
};

The sidebar navigation is automatically generated from:

  1. Your file structure in src/app/docs/
  2. The _meta.js files in each directory

Example _meta.js:

export default {
  index: "Introduction",
  "getting-started": "Getting Started",
  guides: "Guides",
  "api-reference": "API Reference",
};

Styling

Custom Styles

Add custom styles to src/styles/docs-custom.css:

/* Custom documentation styles */
.nextra-content {
  /* Your custom styles */
}

Theme Colors

The docs inherit your global theme colors from src/styles/globals.css.

Best Practices

1. Organize by Feature

Group related documentation together in folders.

2. Use Clear Titles

Make titles descriptive and scannable:

  • ✅ “Installing Dependencies”
  • ❌ “Installation”

3. Add Examples

Include code examples for every concept.

Use relative links to connect related documentation:

See also: [Configuration Guide](/docs/getting-started/configuration)

5. Keep It Updated

Review and update documentation regularly:

  • When you add new features
  • When APIs change
  • When users report confusion

Troubleshooting

MDX Compilation Errors

If you see MDX errors:

  1. Check for unclosed JSX tags
  2. Ensure proper frontmatter formatting (YAML syntax)
  3. Verify code blocks use proper triple backticks

If sidebar navigation doesn’t reflect your changes:

  1. Restart the dev server
  2. Check _meta.js files for syntax errors
  3. Clear Next.js cache: rm -rf .next

Styling Issues

If styles aren’t applying:

  1. Verify CSS imports in src/app/docs/layout.tsx
  2. Check Tailwind config
  3. Restart dev server after config changes

Next Steps

  • Write your first documentation page
  • Customize the theme configuration
  • Add custom components for your docs

Resources

Last updated on
Blog System