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
-
Review 2-3 existing guides in the target category to understand style
-
Choose category from existing or create new
-
Create folder: (category)/guide-slug/
-
Create index.mdx with content
-
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 :
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
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