Your First Tutorial

In this tutorial, you’ll learn how to create a new documentation page with proper frontmatter validation.

What You’ll Learn

By the end of this tutorial, you’ll be able to:

Create a new Markdown page in the correct location
Write valid frontmatter with required fields
Use Content Collections for type-safe content
Preview your changes in the development server

Step 1: Create a New File

First, decide which section your page belongs in:

Guides: For “how-to” instructions
Reference: For technical specifications
Tutorials: For step-by-step learning (like this page!)
Concepts: For explanations of ideas
Troubleshooting: For problem-solving help

Create a new .md file in the appropriate directory:

# Example: Create a new guide
touch src/content/docs/guides/my-new-guide.md

Step 2: Add Frontmatter

Every documentation page needs frontmatter with at least these two fields:

---
title: My New Guide
description: A brief description of what this guide covers
---

Required fields:

title: The page title (shown in navigation and browser tab)
description: A brief summary (used for SEO and page metadata)

Optional fields:

template: “doc” (default) or “splash” for full-width hero pages
sidebar.label: Custom sidebar link text
sidebar.order: Custom sorting order
sidebar.hidden: Hide from navigation

Step 3: Write Content

After the frontmatter, write your content using Markdown:

# My Page Heading

Your content goes here. You can use:

- **Bold text**
- *Italic text*
- [Links](https://example.com)
- Code blocks
- Lists
- And more!

Step 4: Preview Your Changes

Start the development server if it’s not already running:

bun run dev

Navigate to your new page in the browser. The sidebar should automatically include your new page!

Step 5: Validate Your Frontmatter

Try building the site to ensure your frontmatter is valid:

bun run build

If there are any validation errors, you’ll see clear error messages indicating:

Which file has the problem
Which field is invalid
What the expected format is

What’s Next?

Now that you know the basics, try:

Adding more content with rich Markdown formatting
Using MDX components for interactive elements
Customizing the sidebar order and labels
Exploring the Architecture documentation

Summary

You’ve learned how to:

✅ Create a new documentation page
✅ Write valid frontmatter
✅ Preview changes in development
✅ Validate content with build-time checks

Keep exploring the documentation to learn more advanced techniques!