Writing Documentation

This guide explains how to create new documentation pages, the metadata required at the top of files, and the special components available to make your docs interactive.

File Location

Documentation files are located in the content/docs directory. They are written in Markdown (.md).

• Root Level: content/docs/my-page.md becomes /docs/my-page.
• Nested: content/docs/category/my-page.md becomes /docs/category/my-page.
• Ordering: Prefix files or folders with a number (e.g., 1.introduction.md, 2.setup.md) to control their order in the sidebar navigation.

Frontmatter (The header)

Every documentation file should start with a YAML frontmatter block. This block is used to define page metadata.

Copy---
title: My Page Title
description: A brief description of what this page covers.
links:
  doc: https://external-docs.com # Optional: Link to external docs
  api: https://api-reference.com # Optional: Link to API reference
---

Fields:

• title: (Required) The title of the page. Displayed as the main <h1>.
• description: (Recommended) A subtitle for the page, also used for SEO.
• navigation.icon: (Optional) An icon displayed in the sidebar. We use Lucide Icons.
• links: (Optional) Badges displayed at the top for quick access to external resources.

Markdown Basics

You can use standard Markdown syntax:

• # Header 1, ## Header 2, ### Header 3
• **Bold**, *Italic*, ~~Strikethrough~~
• [Link Text](url)
• - List item or 1. Numbered item
• > Blockquotes

Code Blocks

Use fenced code blocks with language identifiers:

Copy```vue
<template>
  <div>Hello World</div>
</template>
```

Copy```typescript
const greeting = "Hello World";
```

Component Previews (MDC)

This template includes custom Markdown Components (MDC) to display interactive UI components and their source code. See the MDC Components guide for detailed documentation.

ComponentPreview

Used to show a working component demo and its source code in a tabbed interface.

Copy::component-preview
---
name: Button
description: A basic button example.
align: center
---
::

The component will automatically:

• Look for the component in components/demo/Button.vue first
• Fall back to components/ui/button/Button.vue if not found
• Display both the interactive preview and source code in tabs

ComponentSource

Used when you only want to show the source code of a component without the interactive preview.

Copy::component-source
---
name: Input
title: components/ui/input/Input.vue
---
::

Advanced Markdown Features

Keyboard Shortcuts

Use the :ContentKbd[] syntax to display keyboard shortcuts:

CopyPress :ContentKbd[⌘ K] to open the command menu.

Tables

Create tables using pipe syntax:

Copy| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| Value 1 | Value 2 | Value 3 |

Callouts

Use callout components for important information:

Copy::callout{type="warning"}
This is a warning callout.
::

File Naming Conventions

• Use lowercase with hyphens: getting-started.md
• Use numbered prefixes for ordering: 1.introduction.md, 2.setup.md
• Group related files in directories: content/docs/1.getting-started/
• Keep filenames descriptive and concise

Next Steps

• Read the Customization Guide
• Check out the MDC Components
• Explore the Composables