@imjp/writenex-astro 1.5.0 → 1.6.1

package/README.md

@@ -8,6 +8,7 @@ Visual editor for Astro content collections - WYSIWYG editing for your Astro sit
 
 ### Key Features
 
+- **Fields API** - TypeScript-first builder pattern with 25+ field types
 - **Zero Config** - Auto-discovers your content collections from `src/content/`
 - **WYSIWYG Editor** - MDXEditor-powered markdown editing with live preview
 - **Smart Schema Detection** - Automatically infers frontmatter schema from existing content
@@ -20,7 +21,6 @@ Visual editor for Astro content collections - WYSIWYG editing for your Astro sit
 - **Search & Filter** - Find content quickly with search and draft filters
 - **Preview Links** - Quick access to preview your content in the browser
 - **Production Safe** - Disabled by default in production builds
-- **Version History** - Automatic shadow copies with restore capability
 
 ## Quick Start
 
@@ -77,51 +77,54 @@ export default defineConfig({
 
 By default, Writenex auto-discovers your content collections from `src/content/` and infers the frontmatter schema from existing files. No configuration needed for most projects.
 
-### Custom Configuration
+### Custom Configuration with Fields API
 
 Create `writenex.config.ts` in your project root for full control:
 
 ```typescript
 // writenex.config.ts
-import { defineConfig } from "@imjp/writenex-astro";
+import { defineConfig, collection, fields } from "@imjp/writenex-astro";
 
 export default defineConfig({
-  // Define collections explicitly
   collections: [
-    {
+    collection({
       name: "blog",
       path: "src/content/blog",
       filePattern: "{slug}.md",
       previewUrl: "/blog/{slug}",
       schema: {
-        title: { type: "string", required: true },
-        description: { type: "string" },
-        pubDate: { type: "date", required: true },
-        updatedDate: { type: "date" },
-        heroImage: { type: "image" },
-        tags: { type: "array", items: "string" },
-        draft: { type: "boolean", default: false },
+        title: fields.text({ label: "Title", validation: { isRequired: true } }),
+        description: fields.text({ label: "Description", multiline: true }),
+        pubDate: fields.date({ label: "Published Date", validation: { isRequired: true } }),
+        updatedDate: fields.datetime({ label: "Last Updated" }),
+        heroImage: fields.image({ label: "Hero Image" }),
+        tags: fields.multiselect({ label: "Tags", options: ["javascript", "typescript", "react", "astro"] }),
+        draft: fields.checkbox({ label: "Draft", defaultValue: true }),
+        body: fields.mdx({ label: "Content", validation: { isRequired: true } }),
       },
-    },
-    {
+    }),
+    collection({
       name: "docs",
       path: "src/content/docs",
       filePattern: "{slug}.md",
       previewUrl: "/docs/{slug}",
-    },
+    }),
   ],
 
-  // Image upload settings
   images: {
-    strategy: "colocated", // 'colocated' | 'public'
-    publicPath: "/images", // For 'public' strategy
-    storagePath: "public/images", // For 'public' strategy
+    strategy: "colocated",
+    publicPath: "/images",
+    storagePath: "public/images",
   },
 
-  // Editor settings
   editor: {
     autosave: true,
-    autosaveInterval: 3000, // milliseconds
+    autosaveInterval: 3000,
+  },
+
+  versionHistory: {
+    enabled: true,
+    maxVersions: 20,
   },
 });
 ```
@@ -135,12 +138,850 @@ export default defineConfig({
 ```typescript
 // astro.config.mjs
 writenex({
-  allowProduction: false, // Keep false for security
+  allowProduction: false,
 });
 ```
 
 The editor is always available at `/_writenex` during development.
 
+## Fields API
+
+The Fields API provides a TypeScript-first builder pattern for defining content schema fields.
+
+### Imports
+
+```typescript
+import { defineConfig, collection, singleton, fields } from "@imjp/writenex-astro/config";
+// or
+import { defineConfig, collection, singleton, fields } from "@writenex/astro/config";
+```
+
+### collection() vs singleton()
+
+- **`collection()`** - For multi-item content (blog posts, docs, products)
+- **`singleton()`** - For single-item content (site settings, about page)
+
+```typescript
+// Multi-item collection
+collection({
+  name: "blog",
+  path: "src/content/blog",
+  schema: { /* field definitions */ }
+})
+
+// Single-item singleton
+singleton({
+  name: "settings",
+  path: "src/content/settings.json",
+  schema: { /* field definitions */ }
+})
+```
+
+## Field Types
+
+### Text Fields
+
+#### `fields.text()`
+
+Single or multi-line text input.
+
+```typescript
+fields.text({ label: "Title" })
+fields.text({ label: "Description", multiline: true })
+fields.text({ 
+  label: "Bio",
+  multiline: true,
+  placeholder: "Tell us about yourself...",
+  validation: { 
+    isRequired: true,
+    minLength: 10,
+    maxLength: 500 
+  }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `description` | `string` | Help text |
+| `multiline` | `boolean` | Multi-line textarea (default: false) |
+| `placeholder` | `string` | Placeholder text |
+| `defaultValue` | `string` | Default value |
+| `validation.isRequired` | `boolean` | Field is required |
+| `validation.minLength` | `number` | Minimum character count |
+| `validation.maxLength` | `number` | Maximum character count |
+| `validation.pattern` | `string` | Regex pattern |
+| `validation.patternDescription` | `string` | Pattern error message |
+
+---
+
+#### `fields.slug()`
+
+URL-friendly slug field with auto-generation support.
+
+```typescript
+fields.slug({ label: "URL Slug" })
+fields.slug({ 
+  name: { label: "Name Slug", placeholder: "my-page" },
+  pathname: { label: "URL Path", placeholder: "/pages/" }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `name.label` | `string` | Name field label |
+| `name.placeholder` | `string` | Name placeholder |
+| `pathname.label` | `string` | Path field label |
+| `pathname.placeholder` | `string` | Path placeholder |
+
+---
+
+#### `fields.url()`
+
+URL input with validation.
+
+```typescript
+fields.url({ label: "Website" })
+fields.url({ 
+  label: "GitHub Profile",
+  placeholder: "https://github.com/username",
+  validation: { isRequired: true }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `placeholder` | `string` | Placeholder URL |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+### Number Fields
+
+#### `fields.number()`
+
+Numeric input for decimals.
+
+```typescript
+fields.number({ label: "Price" })
+fields.number({ 
+  label: "Rating",
+  placeholder: 4.5,
+  validation: { min: 0, max: 5 }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `placeholder` | `number` | Placeholder value |
+| `defaultValue` | `number` | Default value |
+| `validation.isRequired` | `boolean` | Field is required |
+| `validation.min` | `number` | Minimum value |
+| `validation.max` | `number` | Maximum value |
+
+---
+
+#### `fields.integer()`
+
+Whole number input.
+
+```typescript
+fields.integer({ label: "Quantity" })
+fields.integer({ 
+  label: "Year",
+  validation: { min: 1900, max: 2100 }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `placeholder` | `number` | Placeholder value |
+| `defaultValue` | `number` | Default value |
+| `validation.isRequired` | `boolean` | Field is required |
+| `validation.min` | `number` | Minimum value |
+| `validation.max` | `number` | Maximum value |
+
+---
+
+### Selection Fields
+
+#### `fields.select()`
+
+Dropdown selection from options.
+
+```typescript
+fields.select({ 
+  label: "Status",
+  options: ["draft", "published", "archived"],
+  defaultValue: "draft"
+})
+
+fields.select({
+  label: "Category",
+  options: ["technology", "lifestyle", "travel"],
+  validation: { isRequired: true }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `options` | `string[]` | Selectable options (required) |
+| `defaultValue` | `string` | Default option |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.multiselect()`
+
+Multi-select with checkboxes or multi-select UI.
+
+```typescript
+fields.multiselect({ 
+  label: "Tags",
+  options: ["javascript", "typescript", "react", "node"],
+  defaultValue: ["javascript"]
+})
+
+fields.multiselect({
+  label: "Topics",
+  options: ["frontend", "backend", "devops", "mobile"],
+  validation: { isRequired: true }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `options` | `string[]` | Selectable options (required) |
+| `defaultValue` | `string[]` | Default selections |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.checkbox()`
+
+Boolean toggle.
+
+```typescript
+fields.checkbox({ label: "Published" })
+fields.checkbox({ 
+  label: "Featured",
+  defaultValue: false
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `defaultValue` | `boolean` | Default state (default: false) |
+
+---
+
+### Date & Time Fields
+
+#### `fields.date()`
+
+Date picker.
+
+```typescript
+fields.date({ label: "Published Date" })
+fields.date({ 
+  label: "Event Date",
+  defaultValue: "2024-01-15"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `defaultValue` | `string` | Default date (YYYY-MM-DD) |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.datetime()`
+
+Date and time picker.
+
+```typescript
+fields.datetime({ label: "Publish At" })
+fields.datetime({ 
+  label: "Event Date & Time",
+  defaultValue: "2024-01-15T09:00"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `defaultValue` | `string` | Default datetime (ISO format) |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+### File & Media Fields
+
+#### `fields.image()`
+
+Image upload with preview.
+
+```typescript
+fields.image({ label: "Hero Image" })
+fields.image({ 
+  label: "Thumbnail",
+  directory: "public/images/blog",
+  publicPath: "/images/blog"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `directory` | `string` | Storage directory |
+| `publicPath` | `string` | Public URL path |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.file()`
+
+File upload for documents.
+
+```typescript
+fields.file({ label: "Attachment" })
+fields.file({ 
+  label: "PDF Document",
+  directory: "public/files",
+  publicPath: "/files"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `directory` | `string` | Storage directory |
+| `publicPath` | `string` | Public URL path |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+### Structured Fields
+
+#### `fields.object()`
+
+Nested group of fields.
+
+```typescript
+fields.object({
+  label: "Author",
+  fields: {
+    name: fields.text({ label: "Name" }),
+    email: fields.url({ label: "Email" }),
+    bio: fields.text({ label: "Bio", multiline: true }),
+  }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `fields` | `Record<string, FieldDefinition>` | Nested fields (required) |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.array()`
+
+List of items with the same schema.
+
+```typescript
+fields.array({
+  label: "Tags",
+  itemField: fields.text({ label: "Tag" }),
+  itemLabel: "Tag"
+})
+
+fields.array({
+  label: "Links",
+  itemField: fields.object({
+    fields: {
+      title: fields.text({ label: "Title" }),
+      url: fields.url({ label: "URL" }),
+    }
+  }),
+  itemLabel: "Link"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `itemField` | `FieldDefinition` | Schema for each item (required) |
+| `itemLabel` | `string` | Label for items in editor |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.blocks()`
+
+List of items with different block types.
+
+```typescript
+fields.blocks({
+  label: "Content Blocks",
+  blockTypes: {
+    paragraph: {
+      label: "Paragraph",
+      fields: {
+        text: fields.text({ label: "Text", multiline: true })
+      }
+    },
+    quote: {
+      label: "Quote",
+      fields: {
+        text: fields.text({ label: "Quote" }),
+        attribution: fields.text({ label: "Attribution" })
+      }
+    },
+    image: {
+      label: "Image",
+      fields: {
+        src: fields.image({ label: "Image" }),
+        caption: fields.text({ label: "Caption" })
+      }
+    }
+  },
+  itemLabel: "Block"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `blockTypes` | `Record<string, BlockDefinition>` | Block type definitions (required) |
+| `itemLabel` | `string` | Label for blocks in editor |
+
+---
+
+### Reference Fields
+
+#### `fields.relationship()`
+
+Reference to another collection item.
+
+```typescript
+fields.relationship({
+  label: "Author",
+  collection: "authors"
+})
+
+fields.relationship({
+  label: "Related Posts",
+  collection: "blog"
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `collection` | `string` | Target collection name (required) |
+| `validation.isRequired` | `boolean` | Field is required |
+
+---
+
+#### `fields.pathReference()`
+
+Reference to a file path.
+
+```typescript
+fields.pathReference({ label: "Template" })
+fields.pathReference({ 
+  label: "Layout",
+  contentTypes: [".astro", ".mdx"]
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `contentTypes` | `string[]` | Allowed file extensions |
+
+---
+
+### Content Fields
+
+#### `fields.markdoc()`
+
+Markdoc rich content.
+
+```typescript
+fields.markdoc({ label: "Content" })
+fields.markdoc({ 
+  label: "Article Body",
+  validation: { isRequired: true }
+})
+```
+
+---
+
+#### `fields.mdx()`
+
+MDX content with component support.
+
+```typescript
+fields.mdx({ label: "Content" })
+fields.mdx({ 
+  label: "Documentation",
+  validation: { isRequired: true }
+})
+```
+
+---
+
+### Conditional Fields
+
+#### `fields.conditional()`
+
+Show a field based on another field's value.
+
+```typescript
+fields.conditional({
+  label: "CTA Button",
+  matchField: "hasCTA",
+  matchValue: true,
+  showField: fields.object({
+    fields: {
+      text: fields.text({ label: "Button Text" }),
+      url: fields.url({ label: "Link URL" }),
+    }
+  })
+})
+
+fields.conditional({
+  label: "External Link",
+  matchField: "linkType",
+  matchValue: "external",
+  showField: fields.url({ label: "URL" })
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | `string` | Display label |
+| `matchField` | `string` | Field name to check (required) |
+| `matchValue` | `unknown` | Value to match (required) |
+| `showField` | `FieldDefinition` | Field to show when matched (required) |
+
+---
+
+### Child & Nested Fields
+
+#### `fields.child()`
+
+Child document content.
+
+```typescript
+fields.child({ label: "Page Content" })
+```
+
+---
+
+### Cloud & Placeholder Fields
+
+#### `fields.cloudImage()`
+
+Cloud-hosted image (future support).
+
+```typescript
+fields.cloudImage({ label: "Profile Picture" })
+fields.cloudImage({ 
+  label: "Avatar",
+  provider: "cloudinary"
+})
+```
+
+---
+
+#### `fields.empty()`
+
+Placeholder field (renders nothing).
+
+```typescript
+fields.empty({ label: "Reserved" })
+```
+
+---
+
+#### `fields.emptyContent()`
+
+Placeholder for empty content area.
+
+```typescript
+fields.emptyContent()
+```
+
+---
+
+#### `fields.emptyDocument()`
+
+Placeholder for empty document section.
+
+```typescript
+fields.emptyDocument()
+```
+
+---
+
+#### `fields.ignored()`
+
+Field is skipped in forms (useful for computed fields).
+
+```typescript
+fields.ignored({ label: "Internal ID" })
+fields.ignored()
+```
+
+---
+
+## Validation
+
+All fields support validation options:
+
+```typescript
+fields.text({
+  label: "Title",
+  validation: {
+    isRequired: true,
+    minLength: 3,
+    maxLength: 100,
+    pattern: "^[A-Za-z]",
+    patternDescription: "Must start with a letter"
+  }
+})
+
+fields.number({
+  label: "Price",
+  validation: {
+    isRequired: true,
+    min: 0,
+    max: 10000
+  }
+})
+```
+
+| Validation Option | Type | Applies To |
+|-------------------|------|------------|
+| `isRequired` | `boolean` | All fields |
+| `min` | `number` | `number`, `integer` |
+| `max` | `number` | `number`, `integer` |
+| `minLength` | `number` | `text`, `url` |
+| `maxLength` | `number` | `text`, `url` |
+| `pattern` | `string` | `text`, `slug` |
+| `patternDescription` | `string` | `text`, `slug` |
+
+---
+
+## Real-World Examples
+
+### Blog Post Schema
+
+```typescript
+collection({
+  name: "blog",
+  path: "src/content/blog",
+  filePattern: "{slug}.md",
+  previewUrl: "/blog/{slug}",
+  schema: {
+    title: fields.text({ 
+      label: "Title",
+      validation: { isRequired: true, maxLength: 100 }
+    }),
+    slug: fields.slug({ 
+      name: { label: "Slug" },
+      pathname: { label: "Path", placeholder: "/blog/" }
+    }),
+    description: fields.text({ 
+      label: "Description",
+      multiline: true,
+      validation: { maxLength: 300 }
+    }),
+    publishedAt: fields.date({ label: "Published Date" }),
+    updatedAt: fields.datetime({ label: "Last Updated" }),
+    author: fields.relationship({ label: "Author", collection: "authors" }),
+    heroImage: fields.image({ label: "Hero Image" }),
+    tags: fields.multiselect({ 
+      label: "Tags",
+      options: ["javascript", "typescript", "react", "astro", "node"]
+    }),
+    draft: fields.checkbox({ label: "Draft", defaultValue: true }),
+    body: fields.mdx({ label: "Content", validation: { isRequired: true } }),
+  }
+})
+```
+
+### Documentation Schema
+
+```typescript
+collection({
+  name: "docs",
+  path: "src/content/docs",
+  filePattern: "{slug}/index.md",
+  previewUrl: "/docs/{slug}",
+  schema: {
+    title: fields.text({ label: "Title", validation: { isRequired: true } }),
+    description: fields.text({ label: "Description" }),
+    order: fields.integer({ label: "Sort Order" }),
+    category: fields.select({
+      label: "Category",
+      options: ["getting-started", "guides", "api-reference", "tutorials"]
+    }),
+    children: fields.child({ label: "Child Pages" }),
+    body: fields.markdoc({ label: "Content" }),
+  }
+})
+```
+
+### Product Catalog Schema
+
+```typescript
+collection({
+  name: "products",
+  path: "src/content/products",
+  filePattern: "{slug}.md",
+  previewUrl: "/products/{slug}",
+  schema: {
+    name: fields.text({ label: "Product Name", validation: { isRequired: true } }),
+    slug: fields.slug({ name: { label: "URL Slug" } }),
+    price: fields.number({ label: "Price" }),
+    compareAtPrice: fields.number({ label: "Compare At Price" }),
+    sku: fields.text({ label: "SKU" }),
+    description: fields.text({ label: "Description", multiline: true }),
+    images: fields.array({
+      label: "Product Images",
+      itemField: fields.image({ label: "Image" }),
+      itemLabel: "Image"
+    }),
+    category: fields.relationship({ label: "Category", collection: "categories" }),
+    tags: fields.multiselect({ 
+      label: "Tags",
+      options: ["new", "sale", "featured", "bestseller"]
+    }),
+    inStock: fields.checkbox({ label: "In Stock", defaultValue: true }),
+    featured: fields.checkbox({ label: "Featured Product" }),
+    specs: fields.object({
+      label: "Specifications",
+      fields: {
+        weight: fields.text({ label: "Weight" }),
+        dimensions: fields.text({ label: "Dimensions" }),
+        material: fields.text({ label: "Material" }),
+      }
+    }),
+  }
+})
+```
+
+### Author Profile Schema
+
+```typescript
+collection({
+  name: "authors",
+  path: "src/content/authors",
+  filePattern: "{slug}.md",
+  previewUrl: "/authors/{slug}",
+  schema: {
+    name: fields.text({ label: "Name", validation: { isRequired: true } }),
+    slug: fields.slug({ name: { label: "Slug" } }),
+    avatar: fields.image({ label: "Avatar" }),
+    role: fields.select({
+      label: "Role",
+      options: ["author", "editor", "contributor", "admin"],
+      defaultValue: "author"
+    }),
+    bio: fields.text({ label: "Bio", multiline: true }),
+    social: fields.object({
+      label: "Social Links",
+      fields: {
+        twitter: fields.url({ label: "Twitter" }),
+        github: fields.url({ label: "GitHub" }),
+        linkedin: fields.url({ label: "LinkedIn" }),
+        website: fields.url({ label: "Website" }),
+      }
+    }),
+    email: fields.url({ label: "Email" }),
+    featured: fields.checkbox({ label: "Featured Author", defaultValue: false }),
+  }
+})
+```
+
+---
+
+## Migration from Plain Schema
+
+If you have an existing plain schema config, here's how to migrate:
+
+### Before (Plain Schema)
+
+```typescript
+export default defineConfig({
+  collections: [
+    {
+      name: "blog",
+      path: "src/content/blog",
+      schema: {
+        title: { type: "string", required: true },
+        description: { type: "string" },
+        pubDate: { type: "date", required: true },
+        draft: { type: "boolean", default: false },
+        tags: { type: "array", items: "string" },
+        heroImage: { type: "image" },
+      },
+    },
+  ],
+});
+```
+
+### After (Fields API)
+
+```typescript
+import { defineConfig, collection, fields } from "@imjp/writenex-astro/config";
+
+export default defineConfig({
+  collections: [
+    collection({
+      name: "blog",
+      path: "src/content/blog",
+      schema: {
+        title: fields.text({ label: "Title", validation: { isRequired: true } }),
+        description: fields.text({ label: "Description" }),
+        pubDate: fields.date({ label: "Published Date", validation: { isRequired: true } }),
+        draft: fields.checkbox({ label: "Draft", defaultValue: false }),
+        tags: fields.array({ label: "Tags", itemField: fields.text({ label: "Tag" }) }),
+        heroImage: fields.image({ label: "Hero Image" }),
+      },
+    }),
+  ],
+});
+```
+
+### Type Mapping
+
+| Plain Schema | Fields API |
+|--------------|------------|
+| `type: "string"` | `fields.text()` |
+| `type: "number"` | `fields.number()` |
+| `type: "boolean"` | `fields.checkbox()` |
+| `type: "date"` | `fields.date()` |
+| `type: "array"` | `fields.array({ itemField: ... })` |
+| `type: "object"` | `fields.object({ fields: ... })` |
+| `type: "image"` | `fields.image()` |
+
+---
+
 ## Collection Configuration
 
 | Option        | Type     | Description                                 |
@@ -149,31 +990,9 @@ The editor is always available at `/_writenex` during development.
 | `path`        | `string` | Path to collection directory                |
 | `filePattern` | `string` | File naming pattern (e.g., `{slug}.md`)     |
 | `previewUrl`  | `string` | URL pattern for preview links               |
-| `schema`      | `object` | Frontmatter schema definition               |
+| `schema`      | `object` | Frontmatter schema definition (Fields API)  |
 | `images`      | `object` | Override image settings for this collection |
 
-### Schema Field Types
-
-| Type      | Form Component | Example Value           |
-| --------- | -------------- | ----------------------- |
-| `string`  | Text input     | `"Hello World"`         |
-| `number`  | Number input   | `42`                    |
-| `boolean` | Toggle switch  | `true`                  |
-| `date`    | Date picker    | `"2024-01-15"`          |
-| `array`   | Tag input      | `["astro", "tutorial"]` |
-| `image`   | Image uploader | `"./my-post/hero.jpg"`  |
-
-```typescript
-schema: {
-  title: { type: "string", required: true },
-  description: { type: "string" },
-  pubDate: { type: "date", required: true },
-  tags: { type: "array", items: "string" },
-  draft: { type: "boolean", default: false },
-  heroImage: { type: "image" },
-}
-```
-
 ## Image Strategies
 
 ### Colocated (Default)
@@ -244,9 +1063,9 @@ import { defineConfig } from "@imjp/writenex-astro";
 
 export default defineConfig({
   versionHistory: {
-    enabled: true, // Enable/disable version history (default: true)
-    maxVersions: 20, // Max versions per content item (default: 20)
-    storagePath: ".writenex/versions", // Storage path (default)
+    enabled: true,
+    maxVersions: 20,
+    storagePath: ".writenex/versions",
   },
 });
 ```
@@ -394,16 +1213,14 @@ Any token in your pattern that is not in the supported list will be resolved fro
 ```typescript
 // writenex.config.ts
 collections: [
-  {
+  collection({
     name: "docs",
     path: "src/content/docs",
-    filePattern: "{project}/{slug}.md", // Custom token
-  },
+    filePattern: "{project}/{slug}.md",
+  }),
 ];
 ```
 
-When creating content with frontmatter `{ project: "my-app", title: "Getting Started" }`, the file will be created at `src/content/docs/my-app/getting-started.md`.
-
 ## Keyboard Shortcuts
 
 | Shortcut               | Action              |
@@ -504,6 +1321,30 @@ writenex({
 2. Check that files have `.md` extension
 3. Verify frontmatter is valid YAML
 
+### Config file not loading
+
+1. Ensure `writenex.config.ts` is in your project root
+2. Check the file has proper exports: `export default defineConfig({ ... })`
+3. Restart the dev server after making changes
+
+### Field types not rendering correctly
+
+1. Verify the field type is spelled correctly (e.g., `fields.text`, not `fields.string`)
+2. Check that required config properties are provided (e.g., `options` for `select`)
+3. For `object` and `array`, ensure `fields` or `itemField` is properly nested
+
+### Validation not working
+
+1. Ensure `validation` object is inside the field config, not outside
+2. Check that validation rules match the field type (e.g., `min`/`max` for numbers)
+3. Remember `isRequired` only validates on form submission
+
+### Collection not found for relationship
+
+1. Verify the `collection` name matches exactly (case-sensitive)
+2. Ensure the referenced collection is also defined in your config
+3. Check that the referenced collection has at least one item
+
 ### Images not uploading
 
 1. Check file permissions on the target directory
@@ -522,13 +1363,6 @@ writenex({
 - React 18.x or 19.x
 - Node.js 22.12.0+ (Node 18 and 20 are no longer supported)
 
-### Future Plans
-
-- MDX full support (components, imports)
-- CLI wrapper (`npx @imjp/writenex-astro`)
-- Git integration (auto-commit on save)
-- Media library management
-
 ## License
 
 MIT - see [LICENSE](../../LICENSE) for details.