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

Содержание

Введение
Установка
Структура проекта
Создание контента
Конфигурация
Deployment

Введение

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

Настройте docusaurus.config.js:

module.exports = {
  url: 'https://username.github.io',
  baseUrl: '/project-name/',
  organizationName: 'username',
  projectName: 'project-name',
  deploymentBranch: 'gh-pages',
  trailingSlash: false,
};

Запустите команду деплоя:

GIT_USER=<GITHUB_USERNAME> yarn deploy

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

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

Netlify
Vercel
AWS Amplify
Firebase Hosting

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

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

Содержание​

Введение​

Установка​

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

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

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

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

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

Markdown документы​

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

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

docusaurus.config.js​

sidebars.js​

Deployment​

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

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

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

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