Adding Guides to Website Skill

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:

![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

Agent Skills: Adding Guides to Website

Install this agent skill to your local

Skill Files