Documentation System

This project uses Nextra - a powerful documentation framework built for Next.js with excellent MDX support.

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 Pages
Git-based - version control your docs alongside code

Directory Structure

Documentation is organized in the src/pages/docs/ directory:

src/pages/docs/
├── index.mdx              # Documentation home page
├── _meta.ts               # Root navigation configuration
├── getting-started/
│   ├── _meta.ts           # Section navigation
│   ├── installation.mdx
│   └── quickstart.mdx
└── guides/
    ├── _meta.ts
    ├── authentication.mdx
    ├── blog-system.mdx
    └── documentation.mdx

Creating Documentation

Add a New Page

Create a new .mdx file in the appropriate directory:

touch src/pages/docs/guides/my-guide.mdx

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.

Update the _meta.ts in the parent directory:

export default {
  authentication: "Authentication",
  "blog-system": "Blog System",
  "my-guide": "My Guide",
};

Add a New Section

Create a new directory:

mkdir src/pages/docs/my-section

Create _meta.ts for navigation:

export default {
  "page-1": "Page 1",
  "page-2": "Page 2",
};

Add pages to the section:

touch src/pages/docs/my-section/page-1.mdx
touch src/pages/docs/my-section/page-2.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>;
}
```

Links

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:

const config: DocsThemeConfig = {
  logo: <span>Your Docs Logo</span>,
  project: {
    link: "https://github.com/yourusername/yourproject",
  },
  docsRepositoryBase: "https://github.com/yourusername/yourproject/tree/main",
  footer: {
    text: "Your Footer Text",
  },
};

The sidebar navigation is automatically generated from:

Your file structure in src/pages/docs/
The _meta.ts files in each directory

Example _meta.ts:

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.

4. Link Between Pages

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:

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

If sidebar navigation doesn’t reflect your changes:

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

Styling Issues

If styles aren’t applying:

Verify CSS imports in src/pages/_app.tsx
Check Tailwind config
Restart dev server after config changes

Next Steps

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

Resources

Blog System