Merge pull request #1712 from mcclowes/fix/various

Fix/various

Author: pzaichkina

.claude/skills/docusaurus-config/README.md

@@ -0,0 +1,14 @@
+# Docusaurus Config
+
+Work with, validate, and modify Docusaurus project configuration
+
+## Structure
+
+- `SKILL.md` - Main skill instructions
+- `references/` - Detailed documentation loaded as needed
+- `scripts/` - Executable code for deterministic operations
+- `assets/` - Templates, images, or other resources
+
+## Usage
+
+This skill is automatically discovered by Claude when relevant to the task.

.claude/skills/docusaurus-config/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: docusaurus-config
+# IMPORTANT: Keep description on ONE line for Claude Code compatibility
+# prettier-ignore
+description: Use when working with docusaurus.config.js/ts files to validate or modify Docusaurus configuration
+---
+
+# Docusaurus Config
+
+## Quick Start
+
+Configuration lives in `docusaurus.config.js` or `docusaurus.config.ts` at project root.
+
+```typescript
+import { Config } from "@docusaurus/types";
+
+const config: Config = {
+  title: "My Site", // Required
+  url: "https://example.com", // Required, no trailing /
+  baseUrl: "/", // Required, must start and end with /
+
+  favicon: "img/favicon.ico",
+  organizationName: "my-org",
+  projectName: "my-project",
+
+  presets: [
+    [
+      "@docusaurus/preset-classic",
+      {
+        /* options */
+      },
+    ],
+  ],
+  themeConfig: {
+    /* theme config */
+  },
+  customFields: {
+    /* unknown fields go here */
+  },
+};
+
+export default config;
+```
+
+## Core Principles
+
+- **Required**: `title`, `url`, `baseUrl` are mandatory
+- **Custom fields**: Unknown fields must use `customFields` object
+- **Validation**: `url` no trailing slash, `baseUrl` must be `/path/`
+- **Plugins/themes**: Use string or `[name, options]` array format
+
+## Common Tasks
+
+**Before editing**: Read current config to preserve format (JS/TS, ESM/CommonJS)
+
+**After editing**: Verify required fields, URL formats, and restart dev server
+
+## Reference Files
+
+See [references/detailed-guide.md](references/detailed-guide.md) for comprehensive examples

.claude/skills/docusaurus-config/references/detailed-guide.md

@@ -0,0 +1,318 @@
+# Docusaurus Configuration - Detailed Guide
+
+## Configuration File Structure
+
+Docusaurus configuration can be in multiple formats:
+
+### TypeScript (Recommended)
+
+```typescript
+import { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
+
+const config: Config = {
+  // Configuration here
+};
+
+export default config;
+```
+
+### JavaScript (ESM)
+
+```javascript
+export default {
+  // Configuration here
+};
+```
+
+### JavaScript (CommonJS)
+
+```javascript
+module.exports = {
+  // Configuration here
+};
+```
+
+### Async Configuration
+
+```typescript
+export default async function createConfig(): Promise<Config> {
+  // Import ESM-only packages
+  const mdxMermaid = await import("mdx-mermaid");
+
+  return {
+    // Configuration here
+  };
+}
+```
+
+## Required Fields
+
+### title
+
+- Type: `string`
+- Required: Yes
+- Description: Site title for metadata and browser tabs
+
+### url
+
+- Type: `string`
+- Required: Yes
+- Format: Must not end with trailing slash
+- Example: `'https://example.com'`
+- Description: Full URL where site will be hosted
+
+### baseUrl
+
+- Type: `string`
+- Required: Yes
+- Format: Must start and end with `/`
+- Example: `'/'` or `'/docs/'`
+- Description: Path where site is served from
+
+## Common Optional Fields
+
+### Site Metadata
+
+- `tagline`: Short description of your site
+- `favicon`: Path to favicon (relative to static folder)
+- `organizationName`: GitHub org/user name (for deployment)
+- `projectName`: GitHub repo name (for deployment)
+
+### Deployment
+
+- `deploymentBranch`: Branch for deployment (default: 'gh-pages')
+- `trailingSlash`: Boolean or undefined for trailing slash handling
+
+### Internationalization
+
+```typescript
+i18n: {
+  defaultLocale: 'en',
+  locales: ['en', 'fr', 'es'],
+}
+```
+
+## Themes Configuration
+
+### Using Presets (Recommended)
+
+```typescript
+presets: [
+  [
+    '@docusaurus/preset-classic',
+    {
+      docs: {
+        sidebarPath: './sidebars.ts',
+        editUrl: 'https://github.com/user/repo/tree/main/',
+      },
+      blog: {
+        showReadingTime: true,
+      },
+      theme: {
+        customCss: './src/css/custom.css',
+      },
+    },
+  ],
+],
+```
+
+### Direct Theme Configuration
+
+```typescript
+themes: ['@docusaurus/theme-classic'],
+themeConfig: {
+  navbar: {
+    title: 'My Site',
+    logo: {
+      alt: 'My Site Logo',
+      src: 'img/logo.svg',
+    },
+    items: [
+      {to: '/docs/intro', label: 'Docs', position: 'left'},
+    ],
+  },
+  footer: {
+    style: 'dark',
+    links: [],
+    copyright: `Copyright © ${new Date().getFullYear()}`,
+  },
+},
+```
+
+## Plugins
+
+### Adding Plugins
+
+String format (no options):
+
+```typescript
+plugins: ['@docusaurus/plugin-debug'],
+```
+
+Array format (with options):
+
+```typescript
+plugins: [
+  [
+    '@docusaurus/plugin-content-docs',
+    {
+      id: 'community',
+      path: 'community',
+      routeBasePath: 'community',
+    },
+  ],
+],
+```
+
+### Shorthand Notation
+
+Official Docusaurus packages can use shorthand:
+
+- `'classic'` → `'@docusaurus/preset-classic'`
+- `'plugin-debug'` → `'@docusaurus/plugin-debug'`
+
+## Custom Fields
+
+Unknown fields cause validation errors. Use `customFields` for custom data:
+
+```typescript
+customFields: {
+  apiKey: process.env.API_KEY,
+  customValue: 'my-value',
+  complexData: {
+    nested: true,
+  },
+}
+```
+
+Access in components:
+
+```typescript
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+function MyComponent() {
+  const {siteConfig} = useDocusaurusContext();
+  const apiKey = siteConfig.customFields.apiKey;
+
+  return <div>{apiKey}</div>;
+}
+```
+
+## Validation Checklist
+
+When modifying config, verify:
+
+1. **Required fields present**:
+
+   - ✅ `title` exists
+   - ✅ `url` exists and has no trailing slash
+   - ✅ `baseUrl` exists and starts/ends with `/`
+
+2. **Plugins and themes**:
+
+   - ✅ Use proper package names or shorthand
+   - ✅ Options passed as second array element
+   - ✅ No duplicate plugins
+
+3. **Custom data**:
+
+   - ✅ Unknown fields in `customFields` object
+   - ✅ No direct custom properties at root level
+
+4. **File format**:
+
+   - ✅ Valid JS/TS syntax
+   - ✅ Proper export (ESM or CommonJS)
+   - ✅ TypeScript types imported if using TS
+
+5. **Testing**:
+   - ✅ Restart dev server after changes
+   - ✅ Build succeeds: `npm run build`
+   - ✅ No console errors
+
+## Common Patterns
+
+### Multi-Instance Docs
+
+```typescript
+plugins: [
+  [
+    '@docusaurus/plugin-content-docs',
+    {
+      id: 'product',
+      path: 'product',
+      routeBasePath: 'product',
+    },
+  ],
+  [
+    '@docusaurus/plugin-content-docs',
+    {
+      id: 'community',
+      path: 'community',
+      routeBasePath: 'community',
+    },
+  ],
+],
+```
+
+### Environment Variables
+
+```typescript
+const config: Config = {
+  url: process.env.SITE_URL || "https://localhost:3000",
+  customFields: {
+    apiEndpoint: process.env.API_ENDPOINT,
+  },
+};
+```
+
+### Babel Customization
+
+Create `babel.config.js`:
+
+```javascript
+module.exports = {
+  presets: [require.resolve("@docusaurus/babel/preset")],
+  plugins: [
+    // Your custom Babel plugins
+  ],
+};
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**"url must not have a trailing slash"**
+
+- Fix: Change `url: 'https://example.com/'` to `url: 'https://example.com'`
+
+**"baseUrl must start and end with /"**
+
+- Fix: Change `baseUrl: 'docs'` to `baseUrl: '/docs/'`
+
+**"Unknown field 'myField'"**
+
+- Fix: Move to `customFields: { myField: 'value' }`
+
+**"Cannot find module '@docusaurus/types'"**
+
+- Fix: Run `npm install --save-dev @docusaurus/types`
+
+### Best Practices
+
+1. Use TypeScript for better autocomplete and type checking
+2. Always read existing config before modifying
+3. Preserve file format (don't convert ESM to CommonJS)
+4. Test locally before deploying
+5. Use environment variables for deployment-specific values
+6. Document custom fields with comments
+7. Keep config organized with clear sections
+
+## Additional Resources
+
+- [Official Configuration API](https://docusaurus.io/docs/api/docusaurus-config)
+- [Plugin Configuration](https://docusaurus.io/docs/using-plugins)
+- [Theme Configuration](https://docusaurus.io/docs/using-themes)
+- [Deployment Guide](https://docusaurus.io/docs/deployment)