docusaurus-generator

This skill generates end-user documentation using Docusaurus 3.x by analyzing the current project.

Workflow Overview

1. Analyze the project structure to understand what to document
2. Initialize a new Docusaurus 3.x project (or use existing)
3. Generate documentation content from project analysis
4. Configure Docusaurus settings and theme
5. Build & Preview the documentation site

Step 1: Analyze Project

Before generating docs, analyze the project to identify:

• Package structure: Check package.json, monorepo setup
• Existing docs: Look for docs/, README.md, JSDoc comments
• Features: Identify main features from routes, components, APIs
• Configuration: Check for config files that reveal functionality

# Key files to examine
find . -name "README.md" -o -name "*.md" | head -20
ls -la docs/ 2>/dev/null
cat package.json | jq '.name, .description'

Step 2: Initialize Docusaurus

Create a new Docusaurus 3.x project in docs-site/ directory:

npx -y create-docusaurus@latest docs-site classic --typescript

Or if docs already exist, skip to configuration.

Step 3: Generate Documentation Content

Documentation Structure

Organize docs following this structure:

docs-site/docs/
├── intro.md                    # Getting started
├── installation.md             # Installation guide
├── features/
│   ├── feature-1.md
│   └── feature-2.md
├── guides/
│   ├── quick-start.md
│   └── advanced-usage.md
├── configuration/
│   └── settings.md
└── faq.md

Frontmatter Template

Every doc should have proper frontmatter:

---
sidebar_position: 1
title: Page Title
description: Brief description for SEO
---

# Page Title

Content here...

Content Guidelines

• Write for end users, not developers
• Use simple, clear language
• Include screenshots for UI features
• Add code examples where relevant
• Link between related docs

Step 4: Configure Docusaurus

docusaurus.config.ts

Key configuration options:

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

const config: Config = {
  title: 'Project Name',
  tagline: 'Your tagline here',
  favicon: 'img/favicon.ico',
  url: 'https://your-docs-url.com',
  baseUrl: '/',
  
  // Localization
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'vi'],
  },
  
  themeConfig: {
    navbar: {
      title: 'Project Name',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: 'Docs',
        },
      ],
    },
    footer: {
      style: 'dark',
      copyright: `Copyright © ${new Date().getFullYear()}`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

export default config;

Theme Customization

Edit src/css/custom.css for branding:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
}

[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
}

Step 5: Build & Preview

cd docs-site

# Install dependencies
npm install

# Start dev server
npm run start

# Build for production
npm run build

# Serve production build locally
npm run serve

Common Plugins

Search (Algolia or local)

For local search without Algolia:

npm install @easyops-cn/docusaurus-search-local

// docusaurus.config.ts
themes: [
  [
    '@easyops-cn/docusaurus-search-local',
    {
      hashed: true,
      language: ['en', 'vi'],
    },
  ],
],

Blog

Already included in classic template. Configure in docusaurus.config.ts:

blog: {
  showReadingTime: true,
  blogSidebarCount: 'ALL',
},

Versioning

npm run docusaurus docs:version 1.0.0

Multi-language Support

Enable i18n

1. Configure locales in docusaurus.config.ts
2. Create translated docs in i18n/vi/docusaurus-plugin-content-docs/current/
3. Add locale switcher to navbar

navbar: {
  items: [
    {
      type: 'localeDropdown',
      position: 'right',
    },
  ],
},

Translation workflow

# Generate translation files
npm run write-translations -- --locale vi

# Start dev server with locale
npm run start -- --locale vi

Best Practices

1. Keep intro short - Users want to get started quickly
2. Use admonitions for tips, warnings:

   :::tip
   Pro tip here
   :::
   
   :::warning
   Be careful about this
   :::
   

3. Add images to static/img/ and reference as /img/filename.png
4. Use tabs for platform-specific content:

   import Tabs from '@theme/Tabs';
   import TabItem from '@theme/TabItem';
   
   <Tabs>
     <TabItem value="npm" label="npm">npm install</TabItem>
     <TabItem value="yarn" label="Yarn">yarn add</TabItem>
   </Tabs>
   

5. Auto-generate sidebar from folder structure using sidebars.ts