open-circle/repo-website-guide-create

Adding Documentation Guides

This skill provides instructions for adding new documentation guides to the Formisch website.

Directory Structure

Guides are organized under website/src/routes/{framework}/guides/:

website/src/routes/{framework}/guides/
├── menu.md                           # Navigation menu
├── layout.tsx                        # Layout wrapper
├── (category-name)/                  # Route group (with parentheses)
│   └── guide-name/                   # Individual guide folder
│       └── index.mdx                 # Guide content

Categories:

• (get-started) - Introductory content
• (main-concepts) - Core library concepts
• (advanced-guides) - Advanced features

Step-by-Step Process

Step 1: Choose Category

Determine the appropriate category:

• (get-started): Introduction, Installation, LLMs.txt
• (main-concepts): Define form, Create form, Add fields, Handle submission
• (advanced-guides): Controlled fields, Field arrays, TypeScript

Step 2: Create Guide Directory

mkdir -p website/src/routes/{framework}/guides/(category-name)/guide-slug/

• {framework} = solid, qwik, preact, svelte, or vue
• Use kebab-case for guide-slug

Step 3: Create index.mdx

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

import { Link } from '~/components';

# Guide Title

Opening paragraph explaining what the reader will learn.

## Section Heading

Content explaining the topic with clear, concise language.

\`\`\`tsx
// Code example with proper framework imports
import { createForm, Field, Form } from '@formisch/solid';
import \* as v from 'valibot';

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

export default function Example() {
  const form = createForm({ schema: Schema });
  return (
    <Form of={form}>
      <Field of={form} path={['email']}>
        {(field) => <input {...field.props} value={field.input} />}
      </Field>
    </Form>
  );
}
\`\`\`

## Another Section

Continue with additional sections as needed.

Step 4: Update menu.md

Add to website/src/routes/{framework}/guides/menu.md:

## Category Name

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

Content Guidelines

Front Matter

---
title: Guide Title
description: >-
  Multi-line descriptions use >- syntax.
contributors:
  - github-username
---

Internal Links

Use Link component with framework prefix:

import { Link } from '~/components';

See <Link href="/solid/guides/define-your-form/">define your form</Link>.
See <Link href="/solid/api/createForm/">`createForm`</Link>.

Code Examples

• Use tsx for components, ts for utilities
• Import from @formisch/{framework}
• Import Valibot as import * as v from 'valibot'
• Use v.nonEmpty() for non-empty validation (not v.minLength(1))

Framework Terminology

| Framework | API Category | | --------- | ------------ | | Solid | "primitive" | | Qwik | "hook" | | Preact | "hook" | | Vue | "composable" | | Svelte | "rune" |

Formatting

• Bold for emphasis
• inline code for API names, variables, files
• Proper heading hierarchy (h1 → h2 → h3)
• Concise, focused paragraphs

Guide Structure Patterns

Get Started Guide

# Introduction

Opening explanation.

## Highlights

Key features with brief descriptions.

## Basic Example

Simple working code.

## Comparison

Advantages over alternatives.

## Next Steps

Links to related guides.

Main Concepts Guide

# Define Your Form

Explains what the guide covers.

## Step 1: Create Schema

Explanation with code.

## Step 2: Create Form Store

Explanation with code.

## Common Patterns

Variations and alternatives.

## Related

Links to API docs and other guides.

Advanced Guide

# Field Arrays

Overview of the feature.

## When to Use

Scenarios where this applies.

## Implementation

Detailed code examples.

## Edge Cases

Special considerations.

## Performance

Optimization tips.

Code Example Patterns

Basic Form

import { createForm, Field, Form, type SubmitHandler } from '@formisch/solid';
import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

export default function LoginPage() {
  const loginForm = createForm({
    schema: LoginSchema,
  });

  const handleSubmit: SubmitHandler<typeof LoginSchema> = (output) => {
    console.log(output);
  };

  return (
    <Form of={loginForm} onSubmit={handleSubmit}>
      <Field of={loginForm} path={['email']}>
        {(field) => (
          <div>
            <input {...field.props} value={field.input} type="email" />
            {field.errors && <div>{field.errors[0]}</div>}
          </div>
        )}
      </Field>
      <button type="submit" disabled={loginForm.isSubmitting}>
        Login
      </button>
    </Form>
  );
}

Using Primitive vs Component

### Using Field component

\`\`\`tsx

<Field of={form} path={['email']}>
  {(field) => <input {...field.props} value={field.input} />}
</Field>
\`\`\`

### Using useField primitive

\`\`\`tsx
const field = useField(form, { path: ['email'] });
return <input {...field.props} value={field.input} />;
\`\`\`

Checklist

Before submitting:

• [ ] Directory follows pattern: {framework}/guides/(category)/guide-slug/index.mdx
• [ ] Front matter has title, description, contributors
• [ ] All internal links use Link component with framework prefix
• [ ] Code examples use correct framework package
• [ ] Guide added to menu.md in correct category
• [ ] TypeScript examples properly typed
• [ ] No spelling/grammar errors

Source Code Verification

When guides include Formisch APIs, verify correct usage:

• Framework APIs: Check frameworks/{framework}/src/
• Methods: Check packages/methods/src/
• Core types: Check packages/core/src/
• Examples: Check playgrounds/{framework}/src/