docusaurus-generator

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

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

```bash

# 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'

```

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

```bash

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

```

Or if docs already exist, skip to configuration.

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:

```markdown

---

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

docusaurus.config.ts

Key configuration options:

```typescript

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:

```css

: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;

}

```

```bash

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

```

Search (Algolia or local)

For local search without Algolia:

```bash

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

```

```typescript

// 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:

```typescript

blog: {

showReadingTime: true,

blogSidebarCount: 'ALL',

},

```

Versioning

```bash

npm run docusaurus docs:version 1.0.0

```

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

```typescript

navbar: {

items: [

{

type: 'localeDropdown',

position: 'right',

},

],

},

```

Translation workflow

```bash

# Generate translation files

npm run write-translations -- --locale vi

# Start dev server with locale

npm run start -- --locale vi

```

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

```markdown

:::tip

Pro tip here

:::

:::warning

Be careful about this

:::

```

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

```jsx

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

npm install

yarn add

```

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