Перейти к основному содержимому

Руководство по работе с Docusaurus

Содержание​

Введение​

Docusaurus - это современный генератор статических сайтов, разработанный для создания документации. Он построен на React и поддерживает Markdown с расширенными возможностями.

Установка​

Системные требования​

  • Node.js версии 16.14 или выше
  • npm или yarn

Создание нового проекта​

npx create-docusaurus@latest my-website classic
cd my-website

Запуск локального сервера​

npm run start
# или
yarn start

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

my-website/
├── blog/
│   ├── 2021-08-26-welcome.md
│   └── authors.yml
├── docs/
│   ├── intro.md
│   └── tutorial-basics/
├── src/
│   ├── components/
│   └── pages/
├── static/
│   └── img/
├── docusaurus.config.js
├── sidebar.js
└── package.json

Создание контента​

Markdown документы​

Документы создаются в формате Markdown в директории docs/. Каждый документ должен начинаться с frontmatter:

---
id: doc-markdown
title: Документация в Markdown
sidebar_label: Markdown
---

# Ваш контент начинается здесь

Это обычный Markdown-документ.

Специальные компоненты​

Docusaurus предоставляет специальные компоненты для расширения возможностей Markdown:

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

<Tabs>
  <TabItem value="apple" label="Apple">
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
</Tabs>

Конфигурация​

docusaurus.config.js​

Основной файл конфигурации проекта:

module.exports = {
  title: 'Название проекта',
  tagline: 'Описание проекта',
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',
  favicon: 'img/favicon.ico',
  organizationName: 'your-org',
  projectName: 'your-project',
  
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};

sidebars.js​

Конфигурация боковой навигации:

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Введение',
      items: ['intro', 'getting-started'],
    },
    {
      type: 'category',
      label: 'Руководства',
      items: ['tutorial-basics/create-a-page'],
    },
  ],
};

Deployment​

Сборка проекта​

npm run build
# или
yarn build

Публикация на GitHub Pages​

  1. Настройте docusaurus.config.js:
module.exports = {
  url: 'https://username.github.io',
  baseUrl: '/project-name/',
  organizationName: 'username',
  projectName: 'project-name',
  deploymentBranch: 'gh-pages',
  trailingSlash: false,
};
  1. Запустите команду деплоя:
GIT_USER=<GITHUB_USERNAME> yarn deploy

Дополнительные возможности деплоя​

Docusaurus можно развернуть на различных платформах:

  • Netlify
  • Vercel
  • AWS Amplify
  • Firebase Hosting

Для каждой платформы процесс настройки может отличаться, но базовые шаги включают:

  1. Подключение репозитория
  2. Настройка команды сборки: npm run build или yarn build
  3. Указание директории с собранными файлами: build

Рекомендации по использованию​

  1. Организация контента:

    • Используйте четкую структуру директорий
    • Создавайте понятные названия файлов
    • Группируйте связанные документы в поддиректории

  2. Оптимизация изображений:

    • Храните изображения в /static/img/
    • Используйте оптимизированные форматы
    • Указывайте альтернативный текст

  3. Версионирование:

    • Используйте встроенную систему версионирования для документации
    • Создавайте отдельные версии при значительных изменениях API

  4. Поиск:

    • Настройте Algolia DocSearch для улучшения поиска
    • Добавьте метаданные для улучшения результатов поиска

  5. Локализация:

    • Используйте встроенную систему i18n для переводов
    • Создавайте отдельные директории для каждого языка