Writing Docs

MDX is a powerful format that lets you seamlessly write JSX in your Markdown documents. When combined with shadcn/ui, it provides a robust system for creating beautiful, interactive documentation.

Getting Started

File Structure

Organize your documentation with a clear structure:

docs/
├── content/
│   ├── docs/
│   │   ├── getting-started.mdx
│   │   ├── components/
│   │   │   ├── button.mdx
│   │   │   └── input.mdx
│   │   └── guides/
│   │       └── installation.mdx
│   └── blog/
│       └── posts/
└── public/
    └── images/

Creating Your First MDX File

1. Create a new .mdx file in your docs directory
2. Add front matter at the top of the file
3. Write your content using Markdown and components

---
title: Getting Started
description: Learn how to get started with our library
---
 
# Getting Started
 
Welcome to our documentation...

Front Matter Configuration

The front matter provides metadata for your documentation pages:

---
title: Page Title
description: Page description for SEO
---

Additional front matter options:

• toc: Enable/disable table of contents
• section: Group pages into sections
• status: Mark pages as draft/published

Using shadcn/ui Components

Component Integration

Import and use shadcn/ui components directly in your MDX:

import { Button } from "@/components/ui/button"
import { Alert } from "@/components/ui/alert"
 
<Button>Click me</Button>
 
<Alert>Important information here</Alert>

Available Components

shadcn/ui provides several components specifically designed for documentation:

Documentation Components

Please refer to the docs-components page for more information.

Advanced Usage

Custom Components

Create custom components for specific documentation needs:

export function FeatureComparison({ features }) {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Feature</TableHead>
          <TableHead>Description</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {features.map((feature) => (
          <TableRow key={feature.name}>
            <TableCell>{feature.name}</TableCell>
            <TableCell>{feature.description}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}

and configure them in the components/mdx-components.tsx file.

import { FeatureComparison } from "@/components/mdx-components"
 
const components = {
  // ... other components
  FeatureComparison,
  // ... other components
}

Meta Data and SEO

Optimize your documentation for search engines:

---
title: Advanced Features
description: Learn about advanced features and capabilities
keywords: [advanced, features, documentation]
openGraph:
  title: Advanced Features
  description: Comprehensive guide to advanced features
  image: /images/advanced-features.png
---

Troubleshooting

Common Issues

1. Components Not Rendering

   • Check import paths
   • Verify component names
   • Ensure proper MDX configuration

2. Styling Issues

   • Check Tailwind classes
   • Verify theme configuration
   • Inspect component hierarchy

3. Build Errors

   • Update dependencies
   • Clear cache and rebuild
   • Check console for errors

Getting Help

• Check the GitHub repository for issues
• Join the community discussions
• Review the documentation source code

Resources

• MDX Documentation
• shadcn/ui Components
• Next.js Documentation
• Tailwind CSS

Remember to keep your documentation up to date and responsive to user feedback. Good documentation is a living document that grows and improves with your project.