Skip to main content

Docusaurus Quick Start Guide

🚀 Quick Setup (5 minutes)​

cd docs
./setup-docusaurus.sh

This script will:

  • Clean old VitePress artifacts
  • Install Docusaurus dependencies
  • Create favicon from logo
  • Test the build
  • Show next steps

Option 2: Manual Setup​

cd docs

# Install dependencies
npm install

# Start development server
npm run start

# Build for production
npm run build

📋 Quick Commands​

CommandDescription
npm run startStart dev server at http://localhost:3000
npm run buildBuild production site
npm run servePreview production build
npm run clearClear cache
npm run deployDeploy to GitHub Pages

🌐 Development Server​

npm run start

Visit: http://localhost:3000/mcp-adr-analysis-server/

The site will auto-reload when you edit markdown files.

🏗️ Building for Production​

npm run build

Output: build/ directory (ready for deployment)

🚢 Deployment​

Automatic (GitHub Actions)​

Push to main branch - GitHub Actions will automatically:

  1. Build the Docusaurus site
  2. Deploy to GitHub Pages
  3. Available at: https://tosin2013.github.io/mcp-adr-analysis-server/

Manual Deployment​

npm run deploy

📝 Editing Documentation​

File Structure​

docs/
├── tutorials/           # Learning-oriented guides
├── how-to-guides/      # Problem-solving guides
├── reference/          # Technical reference
├── explanation/        # Understanding-oriented
└── ide-rules/          # IDE integration

Adding a New Page​

  1. Create markdown file in appropriate directory:

    touch tutorials/my-new-tutorial.md

  2. Add front matter:

    ---
    id: my-new-tutorial
    title: My New Tutorial
    sidebar_label: New Tutorial
    sidebar_position: 4
    ---

  3. Add to sidebars.js if needed:

    'tutorials/my-new-tutorial',

Markdown Features​

Code Blocks with Syntax Highlighting​

interface MyInterface {
  name: string;
  value: number;
}

Admonitions​

:::note
This is a note
:::

:::tip
This is a tip
:::

:::warning
This is a warning
:::

:::danger
This is dangerous
:::

Mermaid Diagrams​

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Tabs​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    npm install
  </TabItem>
  <TabItem value="yarn" label="Yarn">
    yarn install
  </TabItem>
</Tabs>

🎨 Customization​

Theme Colors​

Edit src/css/custom.css:

:root {
  --ifm-color-primary: #646cff;
  /* Change to your brand color */
}

Logo and Images​

  • Logo: static/img/logo.png
  • Favicon: static/img/favicon.ico
  • OG Image: static/img/og-image.png

Edit docusaurus.config.js:

navbar: {
  items: [
    // Add your nav items
  ],
}

Edit sidebars.js:

{
  type: 'category',
  label: 'My Section',
  items: ['doc1', 'doc2'],
}

🔍 Search Configuration​

Local Search (Default)​

Already configured - works out of the box.

  1. Sign up at https://docsearch.algolia.com/
  2. Get your API keys
  3. Update docusaurus.config.js:
algolia: {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  indexName: 'mcp-adr-analysis-server',
}

🐛 Troubleshooting​

Port Already in Use​

npm run start -- --port 3001

Build Errors​

# Clear cache and rebuild
npm run clear
npm run build

Module Not Found​

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Docusaurus will warn about broken links during build. Fix them by:

  • Using relative paths: /tutorials/my-doc
  • Checking file exists in docs directory
  • Updating onBrokenLinks in config (not recommended)

📚 Resources​

✅ Verification Checklist​

After setup, verify:

  • Dev server starts: npm run start
  • All pages load correctly
  • Navigation works
  • Search works
  • Mermaid diagrams render
  • Code blocks have syntax highlighting
  • Production build succeeds: npm run build
  • GitHub Actions workflow exists: .github/workflows/deploy-docusaurus.yml

🎉 You're Ready!​

Your Docusaurus documentation site is now set up and ready to use. Start the dev server and begin editing your documentation!

npm run start

Need Help? Check the full migration guide or Docusaurus documentation.