repo-website-guide-create

name: repo-website-guide-create description: Create conceptual documentation and tutorial pages for the Valibot website at website/src/routes/guides/. Use when adding guides about schemas, pipelines, async validation, migration, or other topics. Covers directory structure, MDX templates, frontmatter, and content guidelines.

Adding Guides to Website

Guide for creating conceptual documentation at website/src/routes/guides/.

Directory Structure

website/src/routes/guides/
├── menu.md                    # Navigation menu
├── (get-started)/             # Intro, installation, quick start
├── (main-concepts)/           # Schemas, pipelines, parsing
├── (schemas)/                 # Objects, arrays, unions
├── (advanced)/                # Async, i18n, JSON Schema
├── (migration)/               # Version upgrades, Zod migration
└── (category)/guide-slug/
    └── index.mdx              # Guide content

Note: Category folders use parentheses (Qwik route grouping).

Process

1. Review 2-3 existing guides in the target category to understand style
2. Choose category from existing or create new
3. Create folder: (category)/guide-slug/
4. Create index.mdx with content
5. Update menu.md

index.mdx Template

---
title: Guide Title
description: >-
  A concise description of what this guide covers.
contributors:
  - github-username
---

import { ApiList, Link } from '~/components';

# Guide Title

Opening paragraph explaining what the reader will learn.

## Section Heading

Content with clear, concise language.

\`\`\`ts
import \* as v from 'valibot';

const Schema = v.object({
name: v.string(),
email: v.pipe(v.string(), v.email()),
});
\`\`\`

## Another Section

Continue with additional sections as needed.

Use <Link href="/api/pipe/">\`pipe\`</Link> for internal links.

Frontmatter

Required fields:

• title: Page title and navigation label
• description: SEO description (use >- for multi-line)
• contributors: Array of GitHub usernames

Content Guidelines

Code Examples

• Use TypeScript (ts language)
• Import as import * as v from 'valibot';
• Include comments for complex code

Links

Internal links use the Link component:

<Link href="/guides/schemas/">schemas guide</Link>
<Link href="/api/pipe/">\`pipe\`</Link>

Components

<ApiList label="Related schemas" items={['object', 'array', 'string']} />

Formatting

• inline code for API names, variables, file names
• bold for genuine emphasis only — not as inline section labels
• Proper heading hierarchy (h1 title, h2 sections, h3 subsections)

Writing tone

• Write conversational prose, not terse reference-doc style
• Use first-person plural: "we recommend" not "you should"
• Do not use bold as inline section labels (e.g. avoid **Label:** content). Use a proper subheading instead
• Do not prefix blockquotes with bold labels (e.g. avoid > **Note:** ...). A plain > is correct
• Bullet list items do not need a bold prefix on each item

Images

Place images in the same folder as index.mdx:

![Alt text](./diagram-light.jpg)

Consider light/dark theme variants if applicable (e.g., diagram-light.jpg, diagram-dark.jpg).

Update menu.md

Add to /website/src/routes/guides/menu.md:

## Category Name

- [Existing Guide](/guides/existing/)
- [New Guide Title](/guides/guide-slug/)

Maintain logical ordering within categories.

Checklist

• Reviewed existing guides in the same category
• Folder structure: (category)/guide-slug/index.mdx
• Frontmatter: title, description, contributors
• Internal links use Link component
• Code examples use import * as v from 'valibot';
• Added to menu.md
• Style matches existing guides