@vendure-io/docs-provider 0.1.0

package/docs/creating-a-docs-package.md

@@ -0,0 +1,394 @@
+# Creating a Docs Package
+
+This guide walks you through creating a complete documentation package for the Vendure documentation website.
+
+## Project Structure
+
+A docs package follows this recommended structure:
+
+```
+@vendure/docs-my-plugin/
+├── src/
+│   ├── index.ts           # Main entry point, exports manifest
+│   └── manifest.ts        # Manifest definition
+├── docs/
+│   ├── getting-started/
+│   │   ├── introduction.mdx
+│   │   ├── installation.mdx
+│   │   └── configuration.mdx
+│   ├── guides/
+│   │   ├── basic-usage.mdx
+│   │   └── advanced-features.mdx
+│   └── reference/
+│       └── api-overview.mdx
+├── package.json
+└── tsconfig.json
+```
+
+## Step 1: Initialize the Package
+
+Create a new directory and initialize it:
+
+```bash
+mkdir @vendure/docs-my-plugin
+cd @vendure/docs-my-plugin
+npm init -y
+```
+
+Install the required dependency:
+
+```bash
+npm install @vendure-io/docs-provider
+```
+
+## Step 2: Configure TypeScript
+
+Create a `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Step 3: Configure package.json
+
+Update your `package.json` with the correct exports:
+
+```json
+{
+  "name": "@vendure/docs-my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./manifest": {
+      "import": "./src/manifest.ts",
+      "require": "./src/manifest.ts"
+    }
+  },
+  "files": ["src", "docs"],
+  "dependencies": {
+    "@vendure-io/docs-provider": "^0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "keywords": ["vendure", "documentation", "docs"],
+  "license": "MIT"
+}
+```
+
+Key points:
+
+- The `files` array must include both `src` and `docs` directories
+- Export both the main entry point and the manifest separately
+- Use `"type": "module"` for ES module support
+
+## Step 4: Create the Manifest
+
+The manifest defines your documentation structure. Create `src/manifest.ts`:
+
+```typescript
+import type { DocsPackageManifest } from '@vendure-io/docs-provider'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+// Resolve the package root directory
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+// Helper to create absolute file paths
+const file = (relativePath: string) => join(packageRoot, relativePath)
+
+export const manifest: DocsPackageManifest = {
+  // Unique identifier for your package (used in URLs)
+  id: 'my-plugin',
+
+  // Human-readable name shown in the UI
+  name: 'My Plugin Documentation',
+
+  // Semantic version of your documentation
+  version: '1.0.0',
+
+  // Target Vendure version
+  vendureVersion: 'v3',
+
+  // Navigation tree structure
+  navigation: [
+    {
+      title: 'Getting Started',
+      slug: 'getting-started',
+      children: [
+        {
+          title: 'Introduction',
+          slug: 'introduction',
+          file: file('docs/getting-started/introduction.mdx'),
+        },
+        {
+          title: 'Installation',
+          slug: 'installation',
+          file: file('docs/getting-started/installation.mdx'),
+        },
+        {
+          title: 'Configuration',
+          slug: 'configuration',
+          file: file('docs/getting-started/configuration.mdx'),
+        },
+      ],
+    },
+    {
+      title: 'Guides',
+      slug: 'guides',
+      children: [
+        {
+          title: 'Basic Usage',
+          slug: 'basic-usage',
+          file: file('docs/guides/basic-usage.mdx'),
+        },
+        {
+          title: 'Advanced Features',
+          slug: 'advanced-features',
+          file: file('docs/guides/advanced-features.mdx'),
+          badge: 'New', // Optional badge label
+        },
+      ],
+    },
+    {
+      title: 'API Reference',
+      slug: 'reference',
+      file: file('docs/reference/api-overview.mdx'),
+    },
+  ],
+
+  // Optional: Search configuration
+  search: {
+    indexFields: ['title', 'description', 'content', 'keywords'],
+    boosts: {
+      title: 3,
+      keywords: 2,
+      description: 1.5,
+      content: 1,
+    },
+  },
+
+  // Optional: GitHub configuration for edit links
+  github: {
+    repository: 'your-org/your-repo',
+    branch: 'main',
+    docsPath: 'packages/docs-my-plugin',
+  },
+}
+```
+
+### Understanding File Paths
+
+**Important**: File paths in the manifest must be **absolute paths** resolved at module load time. This is because the docs application reads files directly from the file system.
+
+The pattern used above ensures paths are resolved correctly:
+
+```typescript
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const file = (relativePath: string) => join(packageRoot, relativePath)
+```
+
+This resolves paths like:
+
+- `file('docs/getting-started/introduction.mdx')` becomes `/path/to/node_modules/@vendure/docs-my-plugin/docs/getting-started/introduction.mdx`
+
+## Step 5: Export the Manifest
+
+Create `src/index.ts`:
+
+```typescript
+export { manifest } from './manifest'
+```
+
+## Step 6: Write MDX Content
+
+Create your documentation files in the `docs/` directory. Each file must include frontmatter with at least a `title`.
+
+**`docs/getting-started/introduction.mdx`**:
+
+```mdx
+---
+title: Introduction to My Plugin
+description: Learn what My Plugin does and why you should use it
+keywords:
+  - introduction
+  - overview
+  - getting-started
+---
+
+# Introduction to My Plugin
+
+My Plugin extends Vendure with powerful features for managing your e-commerce store.
+
+## Features
+
+- Feature one
+- Feature two
+- Feature three
+
+## Why Use My Plugin?
+
+Explain the value proposition here...
+
+## Next Steps
+
+Ready to get started? Head to the [Installation](/v3/my-plugin/getting-started/installation) guide.
+```
+
+### MDX Features
+
+Your MDX content can use:
+
+**Code blocks with syntax highlighting**:
+
+````mdx
+```typescript
+const config = {
+  plugins: [MyPlugin],
+}
+```
+````
+
+**Admonitions** (if supported by the docs theme):
+
+```mdx
+:::tip
+This is a helpful tip!
+:::
+
+:::caution
+Be careful with this setting.
+:::
+
+:::warning
+This action cannot be undone.
+:::
+```
+
+**Internal links** using absolute paths:
+
+```mdx
+See the [Configuration Guide](/v3/my-plugin/getting-started/configuration) for more details.
+```
+
+## Step 7: Navigation Structure Patterns
+
+### Nested Navigation
+
+Group related pages under a parent node:
+
+```typescript
+{
+  title: 'Guides',
+  slug: 'guides',
+  children: [
+    { title: 'Quick Start', slug: 'quick-start', file: file('docs/guides/quick-start.mdx') },
+    { title: 'Best Practices', slug: 'best-practices', file: file('docs/guides/best-practices.mdx') },
+  ],
+}
+```
+
+This creates URLs like:
+
+- `/v3/my-plugin/guides/quick-start`
+- `/v3/my-plugin/guides/best-practices`
+
+### Deeply Nested Navigation
+
+You can nest up to 3 levels deep:
+
+```typescript
+{
+  title: 'Reference',
+  slug: 'reference',
+  children: [
+    {
+      title: 'Services',
+      slug: 'services',
+      children: [
+        { title: 'MyService', slug: 'my-service', file: file('docs/reference/services/my-service.mdx') },
+      ],
+    },
+  ],
+}
+```
+
+URL: `/v3/my-plugin/reference/services/my-service`
+
+### Top-Level Pages
+
+Pages can also exist at the top level:
+
+```typescript
+{
+  title: 'FAQ',
+  slug: 'faq',
+  file: file('docs/faq.mdx'),
+}
+```
+
+URL: `/v3/my-plugin/faq`
+
+### Using Badges
+
+Highlight new or important pages with badges:
+
+```typescript
+{
+  title: 'New Feature',
+  slug: 'new-feature',
+  file: file('docs/new-feature.mdx'),
+  badge: 'New',
+}
+```
+
+Common badge values: `'New'`, `'Beta'`, `'Deprecated'`, `'Updated'`
+
+## Step 8: Validate Your Manifest
+
+Use the `validateManifest` function to catch errors early:
+
+```typescript
+import { validateManifest, ManifestValidationError } from '@vendure-io/docs-provider'
+import { manifest } from './manifest'
+
+try {
+  validateManifest(manifest)
+  console.log('Manifest is valid!')
+} catch (error) {
+  if (error instanceof ManifestValidationError) {
+    console.error('Validation failed:')
+    error.issues.forEach((issue) => console.error(`  - ${issue}`))
+  }
+}
+```
+
+## Complete Example
+
+For a complete working example, see the [`@vendure-io/docs-demo`](https://github.com/vendure-ecommerce/vendure-io/tree/staging/libs/docs-demo) package in the vendure-io repository.
+
+## Next Steps
+
+- [Manifest Reference](./manifest-reference.md) - Detailed API documentation
+- [Frontmatter Reference](./frontmatter-reference.md) - All frontmatter options
+- [Publishing](./publishing.md) - How to publish your docs package