Docusaurus Generator

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

Workflow Overview

• Analyze the project structure to understand what to document

• Initialize a new Docusaurus 3.x project (or use existing)

• Generate documentation content from project analysis

• Configure Docusaurus settings and theme

• 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

• Configure locales in docusaurus.config.ts

• Create translated docs in i18n/vi/docusaurus-plugin-content-docs/current/

• 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

• Keep intro short - Users want to get started quickly

• Use admonitions for tips, warnings: :::tip Pro tip here :::

:::warning Be careful about this :::

• Add images to static/img/ and reference as /img/filename.png

• 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>

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