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 - `(migration-guides)` - Migration from other form libraries - `(integration-guides)` - Integration with UI component libraries ## 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 - **(migration-guides)**: Migrate from React Hook Form, Migrate from TanStack Form - **(integration-guides)**: shadcn/ui, Chakra UI, Mantine (see `repo-website-integration-guide-create` for the required structure) ### Step 2: Create Guide Directory ```bash mkdir -p website/src/routes/{framework}/guides/(category-name)/guide-slug/ ``` - `{framework}` = angular, preact, qwik, react, react-native, solid, svelte, or vue - Use kebab-case for guide-slug ### Step 3: Create index.mdx ```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`: ```markdown ## Category Name - [Existing Guide](/{framework}/guides/existing/) - [New Guide Title](/{framework}/guides/guide-slug/) ``` ## Content Guidelines ### Front Matter ```yaml --- title: Guide Title description: >- Multi-line descriptions use >- syntax. contributors: - github-username --- ``` ### Internal Links Use `Link` component with framework prefix: ```mdx 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" | | React Native | "hook" | | Angular | "function" / "directive" | | Vue | "composable" | | Svelte | "rune" | ### Formatting - **Bold** for emphasis - `inline code` for API names, variables, files - Proper heading hierarchy (h1 → h2 → h3) - Concise, focused paragraphs - No em-dash pairs (`… — aside — …`); use commas, parentheses, or two sentences. A single trailing em dash is fine. ## Guide Structure Patterns ### Get Started Guide ```mdx # 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 ```mdx # 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 ```mdx # 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 ```tsx 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 ```mdx ### 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/`