Creating Documentation

This guide shows you how to create, organize, and structure documentation pages using this framework.

Understanding the Content Structure

All documentation pages live in src/content/docs/ as Markdown files. The framework automatically:

• Generates routes for each file
• Creates navigation menus
• Indexes content for search
• Generates table of contents

Creating Your First Page

1. Create a New Markdown File

Create a new file in src/content/docs/:

src/content/docs/
├── index.md                    # Introduction
├── getting-started.md          # Getting started guide
├── installation.md             # Installation guide
├── your-new-page.md            # Your new page ← Create here
└── advanced-usage.md           # Advanced features

2. Add Front Matter

Every Markdown file must start with front matter (YAML block between --- markers):

---
title: "Your Page Title"
description: "Brief description for search and metadata"
icon: "book-open"
order: 3
---

# Your Page Title

Content goes here...

3. Front Matter Fields Explained

4. Example Page

---
title: "API Reference"
description: "Complete API documentation"
icon: "book-open"
order: 5
---

# API Reference

## Authentication

Our API uses token-based authentication.

### Getting Your Token

1. Log in to your account
2. Navigate to Settings > API
3. Click "Generate Token"

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/v1/docs

Endpoints

Get All Documents

GET /v1/docs

Response:

{
  "data": [
    {
      "id": "doc-1",
      "title": "Getting Started",
      "content": "..."
    }
  ]
}

Organizing Your Documentation

Directory Structure (Optional)

You can organize pages in subdirectories:

src/content/docs/
├── index.md
├── getting-started.md
├── guides/
│   ├── authentication.md
│   ├── api-usage.md
│   └── deployment.md
└── tutorials/
    ├── basic-setup.md
    └── advanced-features.md

Routes are automatically generated:

• src/content/docs/guides/authentication.md → /docs/guides/authentication
• src/content/docs/tutorials/basic-setup.md → /docs/tutorials/basic-setup

Setting Navigation Order

Use the order field to control sidebar position:

---
title: "Getting Started"
order: 1          # Appears first
---

---
title: "Advanced Usage"
order: 3          # Appears third
---

Note: Use decimal values for finer control:

order: 1.5  # Between order 1 and 2
order: 2.7  # Between order 2 and 3

Writing Content

Supported Markdown Syntax

Headings

# H1 - Page Title
## H2 - Main Section
### H3 - Subsection
#### H4 - Sub-subsection

Text Formatting

**Bold text** or __bold__
*Italic text* or _italic_
~~Strikethrough~~
`Inline code`

Lists

Unordered lists:

- Item 1
- Item 2
  - Nested item
  - Nested item

Ordered lists:

1. First step
2. Second step
3. Third step

Code Blocks

JavaScript:

\`\`\`javascript
function hello() {
  console.log('Hello, World!');
}
\`\`\`

Bash:

\`\`\`bash
npm install
npm run dev
\`\`\`

Links

[Link text](https://example.com)
[Relative link](/docs/getting-started)

Blockquotes

> This is a blockquote
> 
> It can span multiple lines

Tables

| Feature | Description       | Status |
| ------- | ----------------- | ------ |
| Search  | Full-text search  | ✓      |
| Mobile  | Responsive design | ✓      |
| Export  | PDF export        | ✗      |

Using Icons

Available Lucide icons for the icon field:

Add to your front matter:

---
title: "My Page"
icon: "settings-2"
---

Best Practices

1. Clear Headings

Use hierarchical headings:

# Main Title
## Section
### Subsection
#### Detail

# Next Main Topic

2. Code Examples

Show practical examples:

## Installation

```bash
npm install your-package

Usage

import { yourFunction } from 'your-package';
yourFunction();

3. Progressive Disclosure

Start simple, build complexity:

## Basic Usage

For most users, this is all you need...

## Advanced Configuration

If you need more control, you can configure...

## Troubleshooting

If something isn't working...

4. Consistent Formatting

• Use consistent spacing
• Maintain visual hierarchy
• Use lists for multiple items
• Use tables for comparisons

5. Cross-references

Link to other documentation:

For more details, see the [API Reference](/docs/api-reference).

Learn more in the [Getting Started](/docs/getting-started) guide.

Preview Your Changes

1. Make sure dev server is running:

   npm run dev

2. Edit your markdown file

3. The browser automatically refreshes with your changes

4. Your page appears in the navigation menu (sorted by order)

Build and Deploy

When ready to publish:

npm run build

This will:

• Generate static HTML pages
• Create search index (Pagefind)
• Output to dist/ folder
• Ready for deployment

See Deployment Guide for hosting options.

Common Patterns

Tutorial Page

---
title: "Build Your First App"
description: "Step-by-step tutorial"
order: 3
---

# Build Your First App

In this tutorial, you'll learn how to create...

## Prerequisites

- Node.js 22+
- npm

## Step 1: Project Setup

```bash
npm create astro@latest my-app
cd my-app

Step 2: Installation

npm install

Step 3: Run

npm run dev

Next Steps

Now that you have… continue with Advanced Usage.

### Reference Page

```markdown
---
title: "API Reference"
description: "Complete API documentation"
order: 5
---

# API Reference

## GET /docs/{id}

Retrieve a specific document.

### Parameters

| Name | Type   | Required |
| ---- | ------ | -------- |
| id   | string | Yes      |

### Response

```json
{
  "id": "doc-123",
  "title": "Example",
  "content": "..."
}```

Example

curl https://api.example.com/docs/doc-123

Need Help?

• Check existing pages for examples
• See Troubleshooting
• Open an issue on GitHub