repo-website-guide-create

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