@vendure-io/docs-provider 0.1.0

package/docs/frontmatter-reference.md

@@ -0,0 +1,364 @@
+# Frontmatter Reference
+
+Every MDX documentation file must include YAML frontmatter at the top of the file. This document describes all available frontmatter fields and how to use them.
+
+## Basic Structure
+
+Frontmatter is enclosed between triple dashes (`---`) at the start of the file:
+
+```mdx
+---
+title: Page Title
+description: A brief description of the page
+keywords:
+  - keyword1
+  - keyword2
+---
+
+# Page Title
+
+Your content here...
+```
+
+## DocPageMeta Schema
+
+```typescript
+interface DocPageMeta {
+  title: string
+  description?: string
+  keywords?: string[]
+  sidebarLabel?: string
+  hidden?: boolean
+}
+```
+
+## Required Fields
+
+### title
+
+**Type:** `string` (required)
+
+The page title. This is used for:
+
+- The `<title>` HTML element
+- Navigation display (unless overridden by `sidebarLabel`)
+- Search indexing
+- Open Graph metadata
+
+```yaml
+---
+title: Getting Started with My Plugin
+---
+```
+
+**Validation:** Must be a non-empty string.
+
+## Optional Fields
+
+### description
+
+**Type:** `string` (optional)
+
+A brief description of the page content. Used for:
+
+- Meta description tag for SEO
+- Search result snippets
+- Social media previews (Open Graph)
+
+```yaml
+---
+title: Installation Guide
+description: Learn how to install and configure My Plugin in your Vendure project
+---
+```
+
+**Best practices:**
+
+- Keep descriptions between 120-160 characters
+- Include relevant keywords naturally
+- Make it compelling for search results
+
+### keywords
+
+**Type:** `string[]` (optional)
+
+An array of keywords for search indexing. These improve search relevance for specific terms.
+
+```yaml
+---
+title: Custom Payment Integration
+keywords:
+  - payment
+  - stripe
+  - checkout
+  - payment-provider
+---
+```
+
+**Best practices:**
+
+- Use 3-8 relevant keywords
+- Include variations users might search for
+- Don't duplicate words already in the title
+
+### sidebarLabel
+
+**Type:** `string` (optional)
+
+An alternative label to display in the sidebar navigation instead of the full title. Useful when the page title is long but you want a shorter navigation label.
+
+```yaml
+---
+title: Comprehensive Guide to Payment Provider Integration
+sidebarLabel: Payment Providers
+---
+```
+
+### hidden
+
+**Type:** `boolean` (optional, default: `false`)
+
+When set to `true`, the page will be excluded from:
+
+- Sidebar navigation
+- Search results
+- Sitemap generation
+
+The page is still accessible via direct URL.
+
+```yaml
+---
+title: Internal Testing Page
+hidden: true
+---
+```
+
+**Use cases:**
+
+- Draft content not ready for publication
+- Internal documentation
+- Legacy pages being phased out
+
+## Complete Example
+
+```yaml
+---
+title: Building Custom Payment Providers
+description: A comprehensive guide to creating custom payment integrations for your Vendure storefront
+keywords:
+  - payment
+  - integration
+  - custom-provider
+  - stripe
+  - paypal
+sidebarLabel: Custom Payments
+hidden: false
+---
+```
+
+## Utility Functions
+
+### parseFrontmatter
+
+Parse MDX content and extract validated frontmatter.
+
+```typescript
+import { parseFrontmatter } from '@vendure-io/docs-provider'
+
+const mdxContent = `---
+title: My Page
+description: Page description
+---
+
+# Content here
+`
+
+const { meta, content } = parseFrontmatter(mdxContent)
+console.log(meta.title) // "My Page"
+console.log(meta.description) // "Page description"
+console.log(content) // "# Content here"
+```
+
+**Parameters:**
+
+- `rawContent: string` - The raw MDX file content including frontmatter
+- `filePath?: string` - Optional file path for better error messages
+
+**Returns:** `ParsedFrontmatter`
+
+```typescript
+interface ParsedFrontmatter {
+  meta: DocPageMeta
+  content: string
+}
+```
+
+**Throws:** `FrontmatterParseError` if parsing or validation fails
+
+---
+
+### validateFrontmatter
+
+Validate frontmatter data against the schema.
+
+```typescript
+import { validateFrontmatter } from '@vendure-io/docs-provider'
+
+const meta = validateFrontmatter({
+  title: 'My Page',
+  description: 'Description',
+  keywords: ['test'],
+})
+```
+
+**Parameters:**
+
+- `data: unknown` - Raw frontmatter data object
+- `filePath?: string` - Optional file path for error messages
+
+**Returns:** Validated `DocPageMeta`
+
+**Throws:** `FrontmatterParseError` if validation fails
+
+---
+
+### hasFrontmatter
+
+Check if content contains frontmatter.
+
+```typescript
+import { hasFrontmatter } from '@vendure-io/docs-provider'
+
+hasFrontmatter('---\ntitle: Test\n---\nContent') // true
+hasFrontmatter('# Just a heading') // false
+```
+
+Useful for quickly checking file content before attempting to parse.
+
+---
+
+### extractFrontmatterData
+
+Extract raw frontmatter without validation. Useful for quick metadata access.
+
+```typescript
+import { extractFrontmatterData } from '@vendure-io/docs-provider'
+
+const data = extractFrontmatterData(mdxContent)
+console.log(data.title) // Works even with custom fields
+console.log(data.customField) // Preserves non-standard fields
+```
+
+**Note:** This returns unvalidated data. Use `parseFrontmatter` or `validateFrontmatter` when you need type-safe access.
+
+---
+
+## Error Handling
+
+### FrontmatterParseError
+
+Thrown when frontmatter parsing or validation fails.
+
+```typescript
+import { FrontmatterParseError, parseFrontmatter } from '@vendure-io/docs-provider'
+
+try {
+  parseFrontmatter(invalidContent, 'docs/page.mdx')
+} catch (error) {
+  if (error instanceof FrontmatterParseError) {
+    console.error('Parse error:', error.message)
+    console.error('File:', error.filePath)
+    // Error message includes validation details:
+    // "Invalid frontmatter in docs/page.mdx:
+    //   - title: Page title is required"
+  }
+}
+```
+
+**Properties:**
+
+- `message: string` - Human-readable error message with details
+- `filePath?: string` - The file path if provided
+- `originalError?: unknown` - The underlying error (usually Zod validation error)
+
+## Common Validation Errors
+
+### Missing Title
+
+```
+Invalid frontmatter in docs/page.mdx:
+  - title: Page title is required
+```
+
+**Fix:** Add a non-empty `title` field.
+
+### Empty Title
+
+```
+Invalid frontmatter in docs/page.mdx:
+  - title: String must contain at least 1 character(s)
+```
+
+**Fix:** Provide a meaningful title string.
+
+### Invalid Keywords Type
+
+```
+Invalid frontmatter in docs/page.mdx:
+  - keywords: Expected array, received string
+```
+
+**Fix:** Use array syntax for keywords:
+
+```yaml
+# Wrong
+keywords: single-keyword
+
+# Correct
+keywords:
+  - single-keyword
+```
+
+### Invalid Hidden Type
+
+```
+Invalid frontmatter in docs/page.mdx:
+  - hidden: Expected boolean, received string
+```
+
+**Fix:** Use boolean values without quotes:
+
+```yaml
+# Wrong
+hidden: 'true'
+
+# Correct
+hidden: true
+```
+
+## Zod Schema
+
+The frontmatter is validated using this Zod schema:
+
+```typescript
+import { z } from 'zod'
+
+const DocPageMetaSchema = z.object({
+  title: z.string().min(1, 'Page title is required'),
+  description: z.string().optional(),
+  keywords: z.array(z.string()).optional(),
+  sidebarLabel: z.string().optional(),
+  hidden: z.boolean().optional(),
+})
+```
+
+You can import and use this schema directly:
+
+```typescript
+import { DocPageMetaSchema } from '@vendure-io/docs-provider'
+
+const result = DocPageMetaSchema.safeParse(data)
+if (!result.success) {
+  console.error(result.error.issues)
+}
+```

package/docs/getting-started.md

@@ -0,0 +1,156 @@
+# Getting Started
+
+`@vendure-io/docs-provider` is a contract library that enables you to create documentation packages for the [Vendure documentation website](https://docs.vendure.io). It provides TypeScript types, Zod schemas for validation, and utility functions for building and navigating documentation structures.
+
+## Overview
+
+The Vendure documentation system uses a **package-based architecture** where documentation content is distributed as separate npm packages. Each package contains:
+
+- A **manifest** describing the package metadata and navigation structure
+- **MDX files** containing the actual documentation content
+- **Frontmatter** metadata for each page
+
+This approach allows:
+
+- Independent versioning of documentation per package
+- Decentralized documentation authoring
+- Type-safe contracts between docs packages and the docs application
+
+## Installation
+
+```bash
+npm install @vendure-io/docs-provider
+# or
+bun add @vendure-io/docs-provider
+# or
+yarn add @vendure-io/docs-provider
+# or
+pnpm add @vendure-io/docs-provider
+```
+
+## Core Concepts
+
+### Manifest
+
+The manifest is the central configuration file for your documentation package. It defines:
+
+- Package identity (`id`, `name`, `version`)
+- Target Vendure version (`vendureVersion`)
+- Navigation tree structure
+- Optional search and GitHub configuration
+
+```typescript
+import type { DocsPackageManifest } from '@vendure-io/docs-provider'
+
+export const manifest: DocsPackageManifest = {
+  id: 'my-plugin',
+  name: 'My Plugin Documentation',
+  version: '1.0.0',
+  vendureVersion: 'v3',
+  navigation: [
+    // ... navigation structure
+  ],
+}
+```
+
+### Navigation Nodes
+
+Navigation is defined as a tree of nodes. Each node has a `title` and `slug`. Leaf nodes (actual pages) have a `file` property pointing to the MDX content.
+
+```typescript
+{
+  title: 'Getting Started',
+  slug: 'getting-started',
+  children: [
+    {
+      title: 'Installation',
+      slug: 'installation',
+      file: 'docs/getting-started/installation.mdx',
+    },
+  ],
+}
+```
+
+### Frontmatter
+
+Each MDX file must include YAML frontmatter with at least a `title`:
+
+```mdx
+---
+title: Installation Guide
+description: Learn how to install and configure the plugin
+keywords:
+  - install
+  - setup
+---
+
+# Installation Guide
+
+Your content here...
+```
+
+## Quick Example
+
+Here's a minimal docs package structure:
+
+```
+my-docs-package/
+├── src/
+│   ├── index.ts       # Exports the manifest
+│   └── manifest.ts    # Manifest definition
+├── docs/
+│   └── getting-started.mdx
+├── package.json
+└── tsconfig.json
+```
+
+**`src/manifest.ts`**:
+
+```typescript
+import type { DocsPackageManifest } from '@vendure-io/docs-provider'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const file = (relativePath: string) => join(packageRoot, relativePath)
+
+export const manifest: DocsPackageManifest = {
+  id: 'my-plugin',
+  name: 'My Plugin',
+  version: '1.0.0',
+  vendureVersion: 'v3',
+  navigation: [
+    {
+      title: 'Getting Started',
+      slug: 'getting-started',
+      file: file('docs/getting-started.mdx'),
+    },
+  ],
+}
+```
+
+**`src/index.ts`**:
+
+```typescript
+export { manifest } from './manifest'
+```
+
+**`docs/getting-started.mdx`**:
+
+```mdx
+---
+title: Getting Started
+description: Quick start guide for My Plugin
+---
+
+# Getting Started
+
+Welcome to My Plugin documentation!
+```
+
+## Next Steps
+
+- [Creating a Docs Package](./creating-a-docs-package.md) - Complete guide to building a documentation package
+- [Manifest Reference](./manifest-reference.md) - Full API documentation for manifest configuration
+- [Frontmatter Reference](./frontmatter-reference.md) - All available frontmatter options
+- [Publishing](./publishing.md) - How to publish and integrate with vendure.io