Setup Guide

This guide will help you set up and configure the documentation platform for your project.

🚀 Quick Start

Prerequisites

Before setting up the documentation platform, ensure you have:

Node.js 18.0 or higher
npm or pnpm package manager
Git for version control
Basic knowledge of Markdown and React (optional)

Installation

Clone the repository

git clone https://github.com/your-org/docs-platform.git
cd docs-platform

Install dependencies

# Using npm
npm install

# Using pnpm (recommended)
pnpm install

Start development server

# Using npm
npm start

# Using pnpm
pnpm start

The documentation site will be available at http://localhost:3000.

📁 Project Structure

docs-platform/
├── docs/                   # Documentation content
│   ├── daggh/             # DAGGH frontend docs
│   ├── ml-service/        # ML service docs
│   ├── docs-platform/     # Platform docs
│   ├── shared/            # Shared documentation
│   └── api/               # API documentation
├── blog/                  # Blog posts
├── src/                   # Custom components and pages
├── static/                # Static assets
├── docusaurus.config.ts   # Main configuration
├── sidebars.ts           # Sidebar configuration
└── package.json          # Dependencies

⚙️ Configuration

Basic Configuration

The main configuration is in 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: "Peack's Doc",
  tagline: "Comprehensive documentation for all Peack projects",
  favicon: "img/favicon.ico",

  // Production URL
  url: "https://docs.peack.com",
  baseUrl: "/",

  // GitHub deployment config
  organizationName: "peack-team",
  projectName: "docs",

  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",

  // Internationalization
  i18n: {
    defaultLocale: "en",
    locales: ["en"],
  },

  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.ts",
          editUrl: "https://github.com/peack-team/docs/tree/main/",
        },
        blog: {
          showReadingTime: true,
          editUrl: "https://github.com/peack-team/docs/tree/main/",
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    navbar: {
      title: "Peack's Doc",
      logo: {
        alt: "Peack Logo",
        src: "img/logo.svg",
      },
      items: [
        {
          type: "docSidebar",
          sidebarId: "tutorialSidebar",
          position: "left",
          label: "Docs",
        },
        { to: "/blog", label: "Blog", position: "left" },
        {
          href: "https://github.com/peack-team/docs",
          label: "GitHub",
          position: "right",
        },
      ],
    },
    footer: {
      style: "dark",
      links: [
        {
          title: "Documentation",
          items: [
            {
              label: "Getting Started",
              to: "/docs/shared/getting-started",
            },
            {
              label: "API Reference",
              to: "/docs/api/overview",
            },
          ],
        },
        {
          title: "Community",
          items: [
            {
              label: "Discord",
              href: "https://discord.gg/peack",
            },
            {
              label: "GitHub",
              href: "https://github.com/peack-team",
            },
          ],
        },
        {
          title: "More",
          items: [
            {
              label: "Blog",
              to: "/blog",
            },
            {
              label: "Status",
              href: "https://status.peack.com",
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} Peack's Team. Built with Docusaurus.`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  } satisfies Preset.ThemeConfig,
}

export default config

Configure navigation in sidebars.ts:

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

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    "intro",
    {
      type: "category",
      label: "Getting Started",
      items: ["shared/getting-started", "shared/project-overview", "shared/development-workflow"],
    },
    {
      type: "category",
      label: "DAGGH Frontend",
      items: ["daggh/GeneralContext/overview", "daggh/GeneralContext/tech-stack", "daggh/GeneralContext/quick-start"],
    },
    {
      type: "category",
      label: "ML Service",
      items: [
        "ml-service/GeneralContext/overview",
        "ml-service/GeneralContext/setup-guide",
        "ml-service/GeneralContext/architecture",
      ],
    },
    {
      type: "category",
      label: "API Documentation",
      items: [
        "api/overview",
        {
          type: "category",
          label: "DAGGH API",
          items: [
            "api/daggh-api/endpoints",
            "api/daggh-api/authentication",
            "api/daggh-api/examples",
            "api/daggh-api/error-handling",
          ],
        },
        {
          type: "category",
          label: "ML Service API",
          items: [
            "api/ml-service-api/recommendation-endpoints",
            "api/ml-service-api/algorithm-endpoints",
            "api/ml-service-api/data-endpoints",
            "api/ml-service-api/integration-guide",
          ],
        },
      ],
    },
    {
      type: "category",
      label: "Documentation Platform",
      items: [
        "docs-platform/GeneralContext/overview",
        "docs-platform/GeneralContext/setup-guide",
        "docs-platform/GeneralContext/best-practices",
      ],
    },
    {
      type: "category",
      label: "Contributing",
      items: ["shared/contributing", "shared/troubleshooting"],
    },
  ],
}

export default sidebars

🎨 Customization

Custom CSS

Add custom styles in src/css/custom.css:

/* Custom CSS variables */
: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%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

[data-theme="dark"] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

/* Custom component styles */
.hero__title {
  font-size: 3rem;
}

.hero__subtitle {
  font-size: 1.5rem;
  margin-bottom: 2rem;
}

/* API documentation styles */
.api-method {
  padding: 0.2rem 0.6rem;
  border-radius: 4px;
  font-weight: bold;
  font-size: 0.875rem;
  margin-right: 0.5rem;
}

.api-method.get {
  background-color: #61affe;
  color: white;
}

.api-method.post {
  background-color: #49cc90;
  color: white;
}

.api-method.put {
  background-color: #fca130;
  color: white;
}

.api-method.delete {
  background-color: #f93e3e;
  color: white;
}

Custom Components

Create reusable components in src/components/:

// src/components/ApiMethod.tsx
import React from "react"

interface ApiMethodProps {
  method: "GET" | "POST" | "PUT" | "DELETE"
  endpoint: string
}

export default function ApiMethod({ method, endpoint }: ApiMethodProps) {
  return (
    <div style={{ marginBottom: "1rem" }}>
      <span className={`api-method ${method.toLowerCase()}`}>{method}</span>
      <code>{endpoint}</code>
    </div>
  )
}

Use in markdown:

import ApiMethod from "@site/src/components/ApiMethod"

<ApiMethod method="GET" endpoint="/api/movies" />

📝 Content Management

Adding Documentation

Create new markdown files in the appropriate directory under docs/
Add frontmatter with metadata:

---
sidebar_position: 1
title: "Page Title"
description: "Page description for SEO"
tags: [tag1, tag2, tag3]
---

# Your Content Here

Update sidebar configuration in sidebars.ts if needed

Writing Guidelines

Use clear headings with proper hierarchy (H1, H2, H3, etc.)
Include code examples with syntax highlighting
Add tags for better categorization
Write descriptive titles and descriptions
Use relative links for internal references

Markdown Features

Docusaurus supports enhanced markdown:

:::tip
This is a tip callout!
:::

:::warning
This is a warning callout!
:::

:::danger
This is a danger callout!
:::

:::info
This is an info callout!
:::

Code blocks with titles:

src/api/client.js
const apiClient = new ApiClient({
  baseURL: "https://api.example.com",
  apiKey: process.env.API_KEY,
})

Tabs:

import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"

;<Tabs>
  <TabItem value="js" label="JavaScript">
    ```javascript console.log('Hello JavaScript!'); ```
  </TabItem>
  <TabItem value="python" label="Python">
    ```python print("Hello Python!") ```
  </TabItem>
</Tabs>

🌍 Deployment

GitHub Pages

Configure deployment in docusaurus.config.ts:

const config: Config = {
  // ...
  url: "https://your-org.github.io",
  baseUrl: "/docs/",
  organizationName: "your-org",
  projectName: "docs",
  trailingSlash: false,
  // ...
}

Deploy using GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Vercel

Connect repository to Vercel
Configure build settings:
- Build Command: npm run build
- Output Directory: build
- Install Command: npm install

Netlify

Connect repository to Netlify
Configure build settings:
- Build command: npm run build
- Publish directory: build

🔍 Search

Algolia Search

Apply for DocSearch at docsearch.algolia.com
Configure search in docusaurus.config.ts:

const config: Config = {
  // ...
  themeConfig: {
    algolia: {
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexName: "YOUR_INDEX_NAME",
      contextualSearch: true,
    },
    // ...
  },
}

Local Search

For local search without external services:

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

// docusaurus.config.ts
module.exports = {
  // ...
  themes: [
    [
      "@easyops-cn/docusaurus-search-local",
      {
        hashed: true,
        language: ["en"],
        highlightSearchTermsOnTargetPage: true,
      },
    ],
  ],
}

📊 Analytics

Google Analytics

// docusaurus.config.ts
const config: Config = {
  // ...
  presets: [
    [
      "classic",
      {
        gtag: {
          trackingID: "G-YOUR_TRACKING_ID",
          anonymizeIP: true,
        },
        // ...
      },
    ],
  ],
}

🔧 Advanced Features

Multi-instance Setup

For multiple documentation sites:

// docusaurus.config.ts
const config: Config = {
  // ...
  plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        id: "api-docs",
        path: "api-docs",
        routeBasePath: "api",
        sidebarPath: require.resolve("./sidebars-api.js"),
      },
    ],
  ],
}

Versioning

Enable document versioning:

npm run docusaurus docs:version 1.0.0

This creates versioned documentation in the versioned_docs/ directory.

Internationalization

Enable multiple languages:

// docusaurus.config.ts
const config: Config = {
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "es"],
  },
  // ...
}

🛠️ Development Workflow

Local Development

# Start development server
npm start

# Build for production
npm run build

# Serve production build locally
npm run serve

# Clear cache
npm run clear

# Deploy to GitHub Pages
npm run deploy

Content Workflow

Create branch for new content
Write documentation in markdown
Test locally with npm start
Create pull request
Review and merge
Deploy automatically

Quality Checks

# Check for broken links
npm run build

# Lint markdown files
markdownlint docs/**/*.md

# Spell check
cspell "docs/**/*.md"

📚 Best Practices

Content Organization

Use clear hierarchies in your folder structure
Group related content together
Keep file names descriptive and consistent
Use categories in sidebars for logical grouping

Writing Style

Be concise and clear
Use active voice
Include examples for complex concepts
Keep paragraphs short
Use bullet points for lists

Maintenance

Regular updates to keep content current
Monitor analytics to understand user behavior
Fix broken links promptly
Update dependencies regularly
Backup content regularly

🚨 Troubleshooting

Common Issues

Build failures:

Check for broken links
Verify markdown syntax
Ensure all images exist

Slow builds:

Reduce image sizes
Minimize external dependencies
Use build optimization plugins

Search not working:

Verify search provider configuration
Check API keys and credentials
Ensure proper indexing

Getting Help

Documentation: Docusaurus Docs
Community: Discord
GitHub: Issues

Ready to start building? Check out our best practices guide for advanced tips and tricks!

🚀 Quick Start​

Prerequisites​

Installation​

📁 Project Structure​

⚙️ Configuration​

Basic Configuration​

Sidebar Configuration​

🎨 Customization​

Custom CSS​

Custom Components​

📝 Content Management​

Adding Documentation​

Writing Guidelines​

Markdown Features​

🌍 Deployment​

GitHub Pages​

Vercel​

Netlify​

🔍 Search​

Algolia Search​

Local Search​

📊 Analytics​

Google Analytics​

🔧 Advanced Features​

Multi-instance Setup​

Versioning​

Internationalization​

🛠️ Development Workflow​

Local Development​

Content Workflow​

Quality Checks​

📚 Best Practices​

Content Organization​

Writing Style​

Maintenance​

🚨 Troubleshooting​

Common Issues​

Getting Help​