Create a Doc Page

Learn how to create documentation pages using MDX and our documentation layout.

Creating a Doc Page

Documentation pages are created as MDX files in the src/pages/docs directory:

src/pages/docs/
├── index.mdx
├── getting-started/
│   ├── installation.mdx
│   └── configuration.mdx
└── components/
    └── button.mdx

Basic Structure

A documentation page consists of:

---
title: "Your Title"
description: "A brief description of the page"
slug: "create-doc"
---

import DocsLayout from "../../layouts/DocsLayout.astro"


Your content goes here...

Using Components

You can import and use components in your documentation:

<Card className="p-6">
  <h3 className="text-xl font-semibold">Example Card</h3>
  <p className="text-muted-foreground">
    This is an example of using components in docs.
  </p>
  <Button>Learn More</Button>
</Card>

Markdown Features

Code Blocks

Use triple backticks for code blocks with language specification:

```tsx
import { Button } from "@/components/ui/button"

export default function Example() {
  return <Button>Click me</Button>
}
```

Callouts

Use blockquotes for callouts:

Note: This is an important note.

You can include multiple paragraphs.

> **Note:** This is an important note.
>
> You can include multiple paragraphs.

Tables

Create tables using standard markdown syntax:

| Feature | Description |
|---------|-------------|
| MDX     | Use React components in markdown |
| Tailwind| Utility-first CSS framework |

Adding to Navigation

To add your doc page to the sidebar navigation, update src/components/docs/DocsSidebar.astro:

const sidebarNav = [
  {
    title: "Your Section",
    items: [
      {
        title: "Your Page",
        href: "/docs/your-section/your-page",
      },
    ],
  },
]

Best Practices

1. Organization

   • Group related docs in subdirectories
   • Use consistent file naming
   • Keep URL structure logical

2. Content Structure

   • Start with a clear introduction
   • Use proper heading hierarchy
   • Include examples and code snippets
   • Add links to related docs

3. Components

   • Use appropriate components for content types
   • Keep component usage consistent
   • Document component props when needed

4. Metadata

   • Write clear, descriptive titles
   • Include meaningful descriptions
   • Consider adding tags or categories

5. Accessibility

   • Use proper heading structure
   • Add alt text to images
   • Ensure proper color contrast
   • Make code examples screen reader friendly

6. Styling

   • Use consistent spacing
   • Follow typography guidelines
   • Maintain visual hierarchy
   • Consider dark mode