@vendure-io/docs-provider 0.1.0

package/docs/publishing.md

@@ -0,0 +1,352 @@
+# Publishing Your Docs Package
+
+This guide covers how to publish your documentation package and integrate it with the Vendure documentation website.
+
+## Package Naming Conventions
+
+When publishing documentation packages for Vendure, we recommend following these naming conventions:
+
+### npm Scope
+
+Use the `@vendure/` scope for official Vendure documentation packages:
+
+```
+@vendure/docs-core         # Core Vendure documentation
+@vendure/docs-plugins      # Plugin documentation
+@vendure/docs-enterprise   # Enterprise features documentation
+@vendure/docs-my-plugin    # Your custom plugin documentation
+```
+
+For third-party or community packages, you can use your own scope:
+
+```
+@your-org/vendure-docs-my-plugin
+@your-username/vendure-docs-something
+```
+
+### Package ID
+
+The `id` field in your manifest should be:
+
+- Lowercase
+- Use hyphens for word separation
+- Descriptive and unique
+
+```typescript
+// Good
+id: 'my-plugin'
+id: 'payment-stripe'
+id: 'elasticsearch-integration'
+
+// Avoid
+id: 'MyPlugin'
+id: 'my_plugin'
+id: 'docs'
+```
+
+## Preparing for Publication
+
+### 1. Verify Package Structure
+
+Ensure your package has the correct structure:
+
+```
+your-docs-package/
+├── src/
+│   ├── index.ts      # Must export manifest
+│   └── manifest.ts   # Manifest definition
+├── docs/
+│   └── ...           # MDX documentation files
+├── package.json
+└── tsconfig.json
+```
+
+### 2. Configure package.json
+
+```json
+{
+  "name": "@vendure/docs-my-plugin",
+  "version": "1.0.0",
+  "description": "Documentation for My Plugin",
+  "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"
+  },
+  "keywords": ["vendure", "documentation", "docs", "my-plugin"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/your-repo.git",
+    "directory": "packages/docs-my-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Key requirements:
+
+- **`files`**: Must include `src` and `docs` directories
+- **`exports`**: Must export both the main entry and manifest
+- **`publishConfig.access`**: Set to `"public"` for scoped packages
+
+### 3. Validate Your Manifest
+
+Run validation before publishing:
+
+```typescript
+import { validateManifest, ManifestValidationError } from '@vendure-io/docs-provider'
+import { manifest } from './src/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}`))
+    process.exit(1)
+  }
+}
+```
+
+### 4. Verify All Files Exist
+
+Check that all files referenced in the manifest exist:
+
+```typescript
+import { getAllFilePaths } from '@vendure-io/docs-provider'
+import { manifest } from './src/manifest'
+import { existsSync } from 'fs'
+
+const files = getAllFilePaths(manifest)
+const missing = files.filter((file) => !existsSync(file))
+
+if (missing.length > 0) {
+  console.error('Missing files:')
+  missing.forEach((file) => console.error(`  - ${file}`))
+  process.exit(1)
+}
+
+console.log(`All ${files.length} documentation files exist!`)
+```
+
+## Publishing to npm
+
+### First-Time Setup
+
+1. Create an npm account at [npmjs.com](https://www.npmjs.com/)
+2. Login to npm:
+
+```bash
+npm login
+```
+
+3. If using a scope (e.g., `@vendure/`), ensure you have access to publish under that scope
+
+### Publishing
+
+```bash
+# Ensure you're in the package directory
+cd packages/docs-my-plugin
+
+# Run any build steps if needed
+npm run build
+
+# Publish the package
+npm publish --access public
+```
+
+### Versioning
+
+Follow semantic versioning:
+
+- **Patch** (`1.0.1`): Typo fixes, minor content updates
+- **Minor** (`1.1.0`): New pages, new sections
+- **Major** (`2.0.0`): Breaking changes to navigation structure, major rewrites
+
+Update both `package.json` version and `manifest.version`:
+
+```typescript
+export const manifest: DocsPackageManifest = {
+  // ...
+  version: '1.1.0', // Keep in sync with package.json
+  // ...
+}
+```
+
+## Integration with vendure.io
+
+Once your package is published, it needs to be registered in the docs application to appear on vendure.io.
+
+### How Integration Works
+
+The Vendure docs application:
+
+1. Imports your package's manifest at build time
+2. Registers it in a configuration file
+3. Generates static pages for all navigation nodes
+4. Renders MDX content using server-side rendering
+
+### Package Registration
+
+Documentation packages are registered in the docs application's configuration. The configuration maps package names to their display settings:
+
+```typescript
+// Example configuration structure (in the docs app)
+const docsConfig = [
+  {
+    version: 'v3',
+    label: 'v3.x (Latest)',
+    isLatest: true,
+    packages: [
+      {
+        packageName: '@vendure/docs-core',
+        id: 'core',
+        name: 'Vendure Core',
+        description: 'Core Vendure documentation',
+      },
+      {
+        packageName: '@vendure/docs-my-plugin',
+        id: 'my-plugin',
+        name: 'My Plugin',
+        description: 'Documentation for My Plugin',
+      },
+    ],
+  },
+]
+```
+
+### URL Structure
+
+Once registered, your documentation will be available at:
+
+```
+https://docs.vendure.io/v3/{package-id}/{slug-path}
+```
+
+For example:
+
+```
+https://docs.vendure.io/v3/my-plugin/getting-started/installation
+https://docs.vendure.io/v3/my-plugin/guides/advanced-features
+```
+
+### Requesting Integration
+
+To have your docs package added to vendure.io:
+
+1. Ensure your package is published and publicly accessible on npm
+2. Verify the manifest is valid and all files are included
+3. Contact the Vendure team or open an issue on the vendure-io repository
+4. Provide:
+   - Package name (e.g., `@vendure/docs-my-plugin`)
+   - Desired `id` for URLs
+   - Display name
+   - Brief description
+
+## Local Development
+
+### Testing with the Docs App
+
+If you have access to the vendure-io monorepo, you can test your package locally:
+
+1. Add your package as a dependency:
+
+```bash
+cd apps/docs
+bun add @vendure/docs-my-plugin
+```
+
+2. Register it in the docs configuration
+3. Run the docs app:
+
+```bash
+bun run docs:dev
+```
+
+### Using Workspace Links
+
+During development, you can link your package locally:
+
+```bash
+# In your docs package
+npm link
+
+# In the docs app
+npm link @vendure/docs-my-plugin
+```
+
+## Updating Published Documentation
+
+When you update your documentation:
+
+1. Update the content in your MDX files
+2. Update the manifest if navigation changed
+3. Bump the version in `package.json` and `manifest.version`
+4. Publish the new version:
+
+```bash
+npm version patch  # or minor/major
+npm publish
+```
+
+5. The docs application will use the new version on next build/deploy
+
+## Checklist
+
+Before publishing, verify:
+
+- [ ] Package name follows conventions
+- [ ] `manifest.id` is unique and URL-friendly
+- [ ] `manifest.version` matches `package.json` version
+- [ ] `manifest.vendureVersion` is correct
+- [ ] All navigation nodes have valid slugs
+- [ ] All file paths resolve correctly
+- [ ] All MDX files have valid frontmatter
+- [ ] All MDX files have at least a `title` in frontmatter
+- [ ] `package.json` includes `src` and `docs` in `files`
+- [ ] `package.json` has correct exports configuration
+- [ ] Manifest validation passes
+- [ ] All referenced files exist in the package
+
+## Troubleshooting
+
+### Package Not Found After Publishing
+
+- Verify the package is public (`npm view @your-scope/docs-package`)
+- Check that `publishConfig.access` is set to `"public"`
+- Wait a few minutes for npm registry propagation
+
+### Files Missing from Published Package
+
+- Check `files` array in `package.json`
+- Ensure `docs/` directory is included
+- Run `npm pack` to inspect what gets published
+
+### Manifest Validation Errors
+
+- Run the validation script before publishing
+- Check that `id`, `name`, and `version` are non-empty
+- Verify `vendureVersion` is `"v1"`, `"v2"`, or `"v3"`
+- Ensure `version` follows semver format (e.g., `"1.0.0"`)
+
+### File Path Resolution Issues
+
+- Use absolute paths in the manifest via `path.join()`
+- Ensure paths are resolved at module load time
+- Test file access with `fs.existsSync()` before publishing

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@vendure-io/docs-provider",
+  "version": "0.1.0",
+  "description": "Contract types and utilities for Vendure documentation packages",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./loader": {
+      "import": {
+        "types": "./dist/loader.d.ts",
+        "default": "./dist/loader.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publish:local": "bun run build && npm publish --registry http://localhost:4873"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "vendure",
+    "documentation",
+    "docs",
+    "mdx",
+    "contract"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vendure-ecommerce/vendure-io.git",
+    "directory": "libs/docs-provider"
+  }
+}