@vendure-io/docs-provider 0.1.0

package/docs/manifest-reference.md

@@ -0,0 +1,520 @@
+# Manifest Reference
+
+This document provides complete API documentation for all manifest types and utility functions in `@vendure-io/docs-provider`.
+
+## DocsPackageManifest
+
+The main manifest type that describes a documentation package.
+
+```typescript
+interface DocsPackageManifest {
+  id: string
+  name: string
+  version: string
+  vendureVersion: VendureVersion
+  navigation: NavigationNode[]
+  search?: SearchConfig
+  github?: GitHubConfig
+}
+```
+
+### Properties
+
+| Property         | Type               | Required | Description                                        |
+| ---------------- | ------------------ | -------- | -------------------------------------------------- |
+| `id`             | `string`           | Yes      | Unique identifier used in URLs (e.g., `"core"`)    |
+| `name`           | `string`           | Yes      | Human-readable display name                        |
+| `version`        | `string`           | Yes      | Semantic version (e.g., `"3.0.0"`)                 |
+| `vendureVersion` | `VendureVersion`   | Yes      | Target Vendure version (`"v1"`, `"v2"`, or `"v3"`) |
+| `navigation`     | `NavigationNode[]` | Yes      | Array of top-level navigation nodes                |
+| `search`         | `SearchConfig`     | No       | Search indexing configuration                      |
+| `github`         | `GitHubConfig`     | No       | GitHub repository configuration for edit links     |
+
+### Example
+
+```typescript
+const manifest: DocsPackageManifest = {
+  id: 'my-plugin',
+  name: 'My Plugin Documentation',
+  version: '1.0.0',
+  vendureVersion: 'v3',
+  navigation: [
+    {
+      title: 'Getting Started',
+      slug: 'getting-started',
+      file: file('docs/getting-started.mdx'),
+    },
+  ],
+  search: {
+    indexFields: ['title', 'description', 'content'],
+    boosts: { title: 2 },
+  },
+  github: {
+    repository: 'vendure-ecommerce/my-plugin',
+    branch: 'main',
+    docsPath: 'docs',
+  },
+}
+```
+
+---
+
+## NavigationNode
+
+Represents a node in the navigation tree.
+
+```typescript
+interface NavigationNode {
+  title: string
+  slug: string
+  file?: string
+  children?: NavigationNode[]
+  badge?: string
+}
+```
+
+### Properties
+
+| Property   | Type               | Required | Description                                          |
+| ---------- | ------------------ | -------- | ---------------------------------------------------- |
+| `title`    | `string`           | Yes      | Display title shown in navigation                    |
+| `slug`     | `string`           | Yes      | URL slug for this node                               |
+| `file`     | `string`           | No       | Absolute path to MDX file (leaf nodes only)          |
+| `children` | `NavigationNode[]` | No       | Nested child navigation nodes                        |
+| `badge`    | `string`           | No       | Optional badge label (e.g., `"New"`, `"Deprecated"`) |
+
+### Node Types
+
+**Section Node** (has children, no file):
+
+```typescript
+{
+  title: 'Guides',
+  slug: 'guides',
+  children: [
+    // child nodes...
+  ],
+}
+```
+
+**Page Node** (has file, no children):
+
+```typescript
+{
+  title: 'Installation',
+  slug: 'installation',
+  file: file('docs/installation.mdx'),
+}
+```
+
+**Section with Index Page** (has both file and children):
+
+```typescript
+{
+  title: 'Reference',
+  slug: 'reference',
+  file: file('docs/reference/index.mdx'),
+  children: [
+    { title: 'API', slug: 'api', file: file('docs/reference/api.mdx') },
+  ],
+}
+```
+
+---
+
+## VendureVersion
+
+Supported Vendure versions.
+
+```typescript
+type VendureVersion = 'v1' | 'v2' | 'v3'
+```
+
+Use this to indicate which version of Vendure your documentation targets.
+
+---
+
+## SearchConfig
+
+Configuration for search indexing.
+
+```typescript
+interface SearchConfig {
+  indexFields: ('title' | 'description' | 'content' | 'keywords')[]
+  boosts?: Record<string, number>
+}
+```
+
+### Properties
+
+| Property      | Type                     | Required | Description                             |
+| ------------- | ------------------------ | -------- | --------------------------------------- |
+| `indexFields` | `Array`                  | Yes      | Fields to include in search index       |
+| `boosts`      | `Record<string, number>` | No       | Custom boost weights for search ranking |
+
+### Available Index Fields
+
+- `title` - Page title from frontmatter
+- `description` - Page description from frontmatter
+- `content` - Full page content
+- `keywords` - Keywords array from frontmatter
+
+### Example
+
+```typescript
+search: {
+  indexFields: ['title', 'description', 'content', 'keywords'],
+  boosts: {
+    title: 3,       // Title matches are 3x more important
+    keywords: 2,    // Keyword matches are 2x more important
+    description: 1.5,
+    content: 1,
+  },
+}
+```
+
+---
+
+## GitHubConfig
+
+Configuration for GitHub integration (edit links, issue reporting).
+
+```typescript
+interface GitHubConfig {
+  repository: string
+  branch?: string
+  docsPath?: string
+}
+```
+
+### Properties
+
+| Property     | Type     | Required | Default  | Description                                     |
+| ------------ | -------- | -------- | -------- | ----------------------------------------------- |
+| `repository` | `string` | Yes      | -        | GitHub repository in `"owner/repo"` format      |
+| `branch`     | `string` | No       | `"main"` | Branch to use for edit links                    |
+| `docsPath`   | `string` | No       | `""`     | Path prefix within repo for documentation files |
+
+### Example
+
+```typescript
+github: {
+  repository: 'vendure-ecommerce/my-plugin',
+  branch: 'main',
+  docsPath: 'packages/my-plugin/docs',
+}
+```
+
+This generates edit links like:
+`https://github.com/vendure-ecommerce/my-plugin/edit/main/packages/my-plugin/docs/getting-started.mdx`
+
+---
+
+## Utility Functions
+
+### validateManifest
+
+Validates raw data against the manifest schema.
+
+```typescript
+function validateManifest(manifest: unknown): DocsPackageManifest
+```
+
+**Parameters:**
+
+- `manifest` - Raw manifest data to validate
+
+**Returns:** Validated `DocsPackageManifest`
+
+**Throws:** `ManifestValidationError` if validation fails
+
+**Example:**
+
+```typescript
+import { validateManifest, ManifestValidationError } from '@vendure-io/docs-provider'
+
+try {
+  const manifest = validateManifest(rawData)
+  console.log('Valid:', manifest.name)
+} catch (error) {
+  if (error instanceof ManifestValidationError) {
+    console.error('Validation errors:', error.issues)
+  }
+}
+```
+
+---
+
+### findNavigationNode
+
+Find a navigation node by its slug path.
+
+```typescript
+function findNavigationNode(
+  manifest: DocsPackageManifest,
+  slugPath: string,
+): NavigationNode | undefined
+```
+
+**Parameters:**
+
+- `manifest` - The docs package manifest
+- `slugPath` - Slash-separated path (e.g., `"getting-started/installation"`)
+
+**Returns:** Found `NavigationNode` or `undefined`
+
+**Example:**
+
+```typescript
+const node = findNavigationNode(manifest, 'guides/custom-plugins')
+if (node) {
+  console.log(node.title) // "Custom Plugins"
+  console.log(node.file) // "/path/to/docs/guides/custom-plugins.mdx"
+}
+```
+
+---
+
+### flattenNavigation
+
+Flatten the navigation tree into a flat array.
+
+```typescript
+function flattenNavigation(manifest: DocsPackageManifest): FlatNavigationNode[]
+```
+
+**Returns:** Array of `FlatNavigationNode` with full path information
+
+```typescript
+interface FlatNavigationNode extends NavigationNode {
+  path: string // Full path from root (e.g., "getting-started/installation")
+  depth: number // Depth level (0 = root)
+  parentPath?: string // Parent node's path, if any
+}
+```
+
+**Example:**
+
+```typescript
+const flatNodes = flattenNavigation(manifest)
+flatNodes.forEach((node) => {
+  console.log(`${'  '.repeat(node.depth)}${node.title} (${node.path})`)
+})
+
+// Output:
+// Getting Started (getting-started)
+//   Installation (getting-started/installation)
+//   Configuration (getting-started/configuration)
+// Guides (guides)
+//   Custom Plugins (guides/custom-plugins)
+```
+
+---
+
+### buildBreadcrumbs
+
+Build a breadcrumb trail for a given path.
+
+```typescript
+function buildBreadcrumbs(manifest: DocsPackageManifest, slugPath: string): BreadcrumbItem[]
+```
+
+**Returns:** Array of `BreadcrumbItem`
+
+```typescript
+interface BreadcrumbItem {
+  title: string // Display title
+  slug: string // URL slug
+  path: string // Full path from root
+}
+```
+
+**Example:**
+
+```typescript
+const breadcrumbs = buildBreadcrumbs(manifest, 'guides/custom-plugins')
+// [
+//   { title: 'Guides', slug: 'guides', path: 'guides' },
+//   { title: 'Custom Plugins', slug: 'custom-plugins', path: 'guides/custom-plugins' }
+// ]
+```
+
+---
+
+### getLeafNodes
+
+Get all nodes that have files (actual pages).
+
+```typescript
+function getLeafNodes(manifest: DocsPackageManifest): FlatNavigationNode[]
+```
+
+**Returns:** Array of `FlatNavigationNode` with `file` property
+
+**Example:**
+
+```typescript
+const pages = getLeafNodes(manifest)
+console.log(`Found ${pages.length} pages`)
+pages.forEach((page) => {
+  console.log(`${page.title}: ${page.file}`)
+})
+```
+
+---
+
+### getPrevNextNodes
+
+Get the previous and next navigation nodes relative to a path.
+
+```typescript
+function getPrevNextNodes(
+  manifest: DocsPackageManifest,
+  slugPath: string,
+): { prev?: FlatNavigationNode; next?: FlatNavigationNode }
+```
+
+**Returns:** Object with optional `prev` and `next` nodes
+
+**Example:**
+
+```typescript
+const { prev, next } = getPrevNextNodes(manifest, 'getting-started/configuration')
+
+if (prev) {
+  console.log(`Previous: ${prev.title}`) // "Installation"
+}
+if (next) {
+  console.log(`Next: ${next.title}`) // "Custom Plugins"
+}
+```
+
+---
+
+### isNodeActive
+
+Check if a navigation node or any of its children matches a path.
+
+```typescript
+function isNodeActive(node: NavigationNode, currentPath: string): boolean
+```
+
+Useful for determining if a nav section should be expanded.
+
+**Example:**
+
+```typescript
+const gettingStarted = manifest.navigation[0]
+const isActive = isNodeActive(gettingStarted, 'getting-started/installation')
+// true - because "installation" is a child of "getting-started"
+```
+
+---
+
+### getNodesAtDepth
+
+Get all navigation nodes at a specific depth level.
+
+```typescript
+function getNodesAtDepth(manifest: DocsPackageManifest, depth: number): FlatNavigationNode[]
+```
+
+**Parameters:**
+
+- `manifest` - The docs package manifest
+- `depth` - Depth level (0 = root level)
+
+**Example:**
+
+```typescript
+const topLevel = getNodesAtDepth(manifest, 0)
+// Returns: Getting Started, Guides, Reference
+
+const secondLevel = getNodesAtDepth(manifest, 1)
+// Returns: Installation, Configuration, Custom Plugins, etc.
+```
+
+---
+
+### getAllFilePaths
+
+Extract all file paths from the manifest navigation.
+
+```typescript
+function getAllFilePaths(manifest: DocsPackageManifest): string[]
+```
+
+**Returns:** Array of all file paths in the navigation
+
+**Example:**
+
+```typescript
+const files = getAllFilePaths(manifest)
+// [
+//   '/path/to/docs/getting-started/installation.mdx',
+//   '/path/to/docs/getting-started/configuration.mdx',
+//   '/path/to/docs/guides/custom-plugins.mdx',
+//   ...
+// ]
+```
+
+---
+
+## Error Classes
+
+### ManifestValidationError
+
+Thrown when manifest validation fails.
+
+```typescript
+class ManifestValidationError extends Error {
+  readonly issues: string[]
+}
+```
+
+**Properties:**
+
+- `issues` - Array of human-readable validation error messages
+
+**Example:**
+
+```typescript
+try {
+  validateManifest({ id: 'test' }) // Missing required fields
+} catch (error) {
+  if (error instanceof ManifestValidationError) {
+    error.issues.forEach((issue) => console.error(issue))
+    // "name: Package name is required"
+    // "version: Version must be valid semver"
+    // etc.
+  }
+}
+```
+
+---
+
+## Zod Schemas
+
+All types have corresponding Zod schemas for runtime validation:
+
+```typescript
+import {
+  DocsPackageManifestSchema,
+  NavigationNodeSchema,
+  SearchConfigSchema,
+  GitHubConfigSchema,
+  VendureVersionSchema,
+  FlatNavigationNodeSchema,
+  BreadcrumbItemSchema,
+} from '@vendure-io/docs-provider'
+
+// Use with Zod's parse method
+const result = DocsPackageManifestSchema.safeParse(rawData)
+if (result.success) {
+  const manifest = result.data
+} else {
+  console.error(result.error.issues)
+}
+```
+
+These schemas are useful when you need fine-grained control over validation or want to integrate with other Zod-based validation workflows.