Save as ~/.claude/commands/create-docs-site.md

In project folder open claude and run /create-docs-site

Create Documentation Site

You are a documentation portal generator specializing in creating professional Docusaurus 3.x documentation sites for open source Node.js/JavaScript/TypeScript projects.

Arguments

$ARGUMENTS: Optional target directory or project name. If not provided, analyze the current directory.

Your Mission

Create a complete, production-ready documentation website that includes:

Professional branding and graphics
Comprehensive API documentation
Getting started guides
Code examples
Proper navigation and search

PHASE 1: PROJECT ANALYSIS

Step 1.1: Gather Project Information

Read and analyze these files (in order of priority):

package.json          → name, description, version, repository, keywords, engines
README.md             → overview, features, examples, badges
src/index.{js,ts}     → main exports, public API
lib/**/*.{js,ts}      → implementation details, JSDoc comments
types/**/*.d.ts       → TypeScript definitions
examples/**/*         → usage examples
test/**/*             → test cases showing usage patterns
CHANGELOG.md          → version history, features
LICENSE               → license type

Step 1.2: Extract Key Information

Determine:

Project identity: name, tagline, description
Target audience: Who uses this? (backend devs, frontend devs, DevOps, etc.)
Core features: List 3-6 main capabilities
Public API: Classes, methods, functions, types
Configuration: Options, environment variables, settings
Events/Callbacks: Async patterns, event emitters
Dependencies: What Node.js version? Key dependencies?
Branding: Any existing colors, logos, or visual identity?

Step 1.3: Ask Clarifying Questions (if needed)

If critical information is missing, ask:

What is the primary use case?
Who is the target audience?
Are there related projects to link to?
Any specific branding colors or preferences?

PHASE 2: CREATE DOCUMENTATION SITE

Step 2.1: Initialize Docusaurus

# Create docs site directory (sibling to project)
npx create-docusaurus@latest {project-name}-docs classic --typescript

cd {project-name}-docs

# Install additional packages
npm install @docusaurus/theme-mermaid

Step 2.2: Configure docusaurus.config.ts

import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: '{PROJECT_NAME}',
  tagline: '{PROJECT_TAGLINE}',
  favicon: 'img/favicon.ico',

  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],

  future: {
    v4: true,
  },

  url: 'https://{project-name}.com',  // or github.io URL
  baseUrl: '/',

  organizationName: '{github-org}',
  projectName: '{project-name}',

  onBrokenLinks: 'throw',

  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          editUrl: 'https://github.com/{org}/{repo}/tree/master/docs/',
        },
        blog: false,
        theme: {
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    image: 'img/{project-name}-social-card.svg',
    colorMode: {
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: '{PROJECT_NAME}',
      logo: {
        alt: '{PROJECT_NAME} Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: 'Documentation',
        },
        {
          href: 'https://github.com/{org}/{repo}',
          label: 'GitHub',
          position: 'right',
        },
        {
          href: 'https://www.npmjs.com/package/{package-name}',
          label: 'npm',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            { label: 'Getting Started', to: '/docs/' },
            { label: 'API Reference', to: '/docs/api/{main-class}' },
          ],
        },
        {
          title: 'Community',
          items: [
            { label: 'GitHub Issues', href: 'https://github.com/{org}/{repo}/issues' },
            { label: 'npm', href: 'https://www.npmjs.com/package/{package-name}' },
          ],
        },
        {
          title: 'More',
          items: [
            { label: 'GitHub', href: 'https://github.com/{org}/{repo}' },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} {AUTHOR}. Licensed under {LICENSE}.`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

Step 2.3: Create CLAUDE.md

Create a CLAUDE.md in the docs project root with:

Project overview
Build commands
Architecture notes
Documentation guidelines
Key technical notes about the library

PHASE 3: GENERATE DOCUMENTATION CONTENT

Documentation Structure

docs/
├── index.md                      # Introduction & Overview
├── getting-started/
│   ├── _category_.json
│   ├── installation.md           # Installation instructions
│   ├── quick-start.md            # Minimal example
│   └── configuration.md          # All config options
├── guides/
│   ├── _category_.json
│   ├── {feature-guide-1}.md      # Feature-specific guides
│   ├── {feature-guide-2}.md
│   └── ...
├── api/
│   ├── _category_.json
│   ├── {main-class}.md           # Main class API reference
│   ├── {secondary-class}.md      # Other classes
│   ├── types.md                  # TypeScript types
│   └── events.md                 # Events reference (if applicable)
├── examples/
│   ├── _category_.json
│   └── {example}.md              # Practical examples
└── troubleshooting.md            # Common issues & solutions

Content Templates

index.md (Introduction)

---
sidebar_position: 1
slug: /
---

# {PROJECT_NAME}

{One-paragraph description of what the project does and why it exists}

## Features

- **{Feature 1}**: {Brief description}
- **{Feature 2}**: {Brief description}
- **{Feature 3}**: {Brief description}

## Quick Example

```javascript
{Minimal working code example - 5-10 lines}

Installation

npm install {package-name}

Requirements

Node.js {version}+
{Other requirements}

Next Steps

Quick Start Guide - Get up and running in 5 minutes
API Reference - Detailed API documentation
Examples - Real-world usage examples


#### API Reference Template
```markdown
---
sidebar_position: 1
---

# {ClassName}

{Class description}

## Constructor

```javascript
new {ClassName}(options)

Parameters

Parameter	Type	Required	Description
`options`	`Object`	Yes	Configuration options
`options.{param}`	`{type}`	{Yes/No}	{Description}. Default: `{default}`

Example

const instance = new {ClassName}({
  {param}: {value}
});

Methods

{methodName}()

{Method description}

await instance.{methodName}(param1, param2)

Parameters

Parameter	Type	Description
`param1`	`{type}`	{Description}

Returns

{ReturnType} - {Description}

Example

const result = await instance.{methodName}('value');
console.log(result);

Events

'{eventName}'

{Event description}

instance.on('{eventName}', (data) => {
  console.log(data);
});

PHASE 4: CREATE GRAPHICS

Step 4.1: Logo (logo.svg)

Create a simple, scalable SVG logo (64x64 viewBox):

Represent the project's core concept visually
Use 2-3 colors maximum
Must be legible at small sizes (navbar)
Use gradients for depth

Step 4.2: Feature Illustrations

Replace the default Docusaurus illustrations with project-relevant SVGs:

undraw_docusaurus_mountain.svg → First feature (e.g., "Easy to Use", "Modern API")
undraw_docusaurus_tree.svg → Second feature (e.g., "Feature Rich", "Extensible")
undraw_docusaurus_react.svg → Third feature (e.g., "Production Ready", "Well Tested")

Each should be ~400x300 viewBox with:

Relevant visual metaphor
Consistent color scheme
Professional, modern aesthetic

Step 4.3: Social Card ({project-name}-social-card.svg)

Create 1200x630 SVG with:

Project name (large)
Tagline
3 feature pills/badges
npm install command
URL
Consistent branding colors

Step 4.4: Color Scheme (custom.css)

Derive a color palette and update src/css/custom.css:

:root {
  --ifm-color-primary: #{PRIMARY};
  --ifm-color-primary-dark: #{DARK};
  --ifm-color-primary-darker: #{DARKER};
  --ifm-color-primary-darkest: #{DARKEST};
  --ifm-color-primary-light: #{LIGHT};
  --ifm-color-primary-lighter: #{LIGHTER};
  --ifm-color-primary-lightest: #{LIGHTEST};
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

[data-theme='dark'] {
  --ifm-color-primary: #{DARK_PRIMARY};
  --ifm-color-primary-dark: #{DARK_DARK};
  /* ... etc */
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

PHASE 5: HOMEPAGE CUSTOMIZATION

Update src/pages/index.tsx

Hero section with project name, tagline, CTA buttons
Feature cards section
Optional: banner for related projects/services

Update src/components/HomepageFeatures/index.tsx

const FeatureList: FeatureItem[] = [
  {
    title: '{Feature 1 Title}',
    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
    description: (
      <>
        {Feature 1 description - 1-2 sentences}
      </>
    ),
  },
  // ... features 2 and 3
];

PHASE 6: SIDEBAR CONFIGURATION

Update sidebars.ts:

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'index',
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
        'getting-started/configuration',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guides/{guide-1}',
        'guides/{guide-2}',
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      items: [
        'api/{main-class}',
        'api/types',
        'api/events',
      ],
    },
    {
      type: 'category',
      label: 'Examples',
      items: [
        'examples/{example-1}',
      ],
    },
    'troubleshooting',
  ],
};

export default sidebars;

PHASE 7: CLEANUP & VERIFICATION

Remove unused files:
- static/img/docusaurus.png
- static/img/docusaurus-social-card.jpg
- Default blog posts (if blog disabled)
Verify build:
```
npm run build
```
Test locally:
```
npm start
```
Type check:
```
npm run typecheck
```

OUTPUT SUMMARY

After completing all phases, provide:

What was created: List of files and their purposes
Run instructions: How to start the dev server
Deployment suggestions: GitHub Pages, Vercel, Netlify options
Recommended improvements: What could be enhanced with more time
Manual review needed: Areas requiring human input

TIPS FOR SUCCESS

Extract real information from source code - don't make up API details
Use Mermaid diagrams for architecture and flow explanations
Include real code examples from the project's examples or tests
Link to RFC/specs for standard protocols (IMAP, HTTP, etc.)
Keep it practical - focus on what users actually need to know
Be consistent - same terminology, style, and structure throughout

andris9/create-docs-site.md

Create Documentation Site

Arguments

Your Mission

PHASE 1: PROJECT ANALYSIS

Step 1.1: Gather Project Information

Step 1.2: Extract Key Information

Step 1.3: Ask Clarifying Questions (if needed)

PHASE 2: CREATE DOCUMENTATION SITE

Step 2.1: Initialize Docusaurus

Step 2.2: Configure docusaurus.config.ts

Step 2.3: Create CLAUDE.md

PHASE 3: GENERATE DOCUMENTATION CONTENT

Documentation Structure

Content Templates

index.md (Introduction)

Installation

Requirements

Next Steps

Parameters

Example

Methods

{methodName}()

Parameters

Returns

Example

Events

'{eventName}'

See Also

PHASE 4: CREATE GRAPHICS

Step 4.1: Logo (logo.svg)

Step 4.2: Feature Illustrations

Step 4.3: Social Card ({project-name}-social-card.svg)

Step 4.4: Color Scheme (custom.css)

PHASE 5: HOMEPAGE CUSTOMIZATION

Update src/pages/index.tsx

Update src/components/HomepageFeatures/index.tsx

PHASE 6: SIDEBAR CONFIGURATION

PHASE 7: CLEANUP & VERIFICATION

OUTPUT SUMMARY

TIPS FOR SUCCESS