Разработка сайта на Docusaurus (документация)

Разработка сайта на Docusaurus (документация)

Docusaurus — React-фреймворк для документации, созданный Meta. Генерирует статический сайт из Markdown/MDX-файлов. Встроены: версионирование, i18n, полнотекстовый поиск через Algolia, sidebar-навигация.

Инициализация

npx create-docusaurus@latest my-docs classic --typescript
cd my-docs
npm run start

Структура проекта

my-docs/
├── docusaurus.config.ts   # основной конфиг
├── sidebars.ts            # конфиг sidebar
├── docs/                  # документация
│   ├── intro.md
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── configuration.md
│   └── api/
│       └── reference.md
├── blog/                  # блог (опционально)
├── src/
│   ├── components/
│   ├── css/custom.css
│   └── pages/            # кастомные страницы (React)
└── static/                # статические файлы

docusaurus.config.ts

import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Project',
  tagline: 'Simple and fast',
  url: 'https://docs.myproject.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  i18n: { defaultLocale: 'ru', locales: ['ru', 'en'] },

  presets: [['classic', {
    docs: {
      sidebarPath: './sidebars.ts',
      editUrl: 'https://github.com/my-org/my-docs/tree/main/',
      showLastUpdateTime: true,
      showLastUpdateAuthor: true,
    },
    theme: { customCss: './src/css/custom.css' },
  } satisfies Preset.Options]],

  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_KEY',
      indexName: 'my-project-docs',
    },
    navbar: {
      title: 'My Project',
      items: [
        { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: 'Docs' },
        { type: 'docsVersionDropdown' },
        { type: 'localeDropdown' },
      ],
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

MDX-компоненты

---
title: API Reference
description: Complete API reference for My Project
---

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

# API Reference

<Tabs>
  <TabItem value="curl" label="cURL">
    ```bash
    curl -X POST https://api.myproject.com/v1/users \
      -H "Authorization: Bearer TOKEN" \
      -d '{"name": "John"}'
    ```
  </TabItem>
  <TabItem value="js" label="JavaScript">
    ```typescript
    const user = await client.users.create({ name: 'John' });
    ```
  </TabItem>
</Tabs>

Запуск и базовая настройка Docusaurus-сайта с 20–50 страницами документации — 3–5 дней.