Как создать и развернуть веб-сайт документации с помощью Docusaurus и Netlify

Первоначально опубликовано в моем личном блоге.

Веб-сайты документации используются для того, чтобы помочь людям узнать о вашем продукте или решении. В частности, для разработчиков это важный ресурс, помогающий другим разработчикам узнать больше о вашем инструменте и лучше понять, как его использовать.

В этом уроке вы узнаете, как создать документацию с помощью Docusaurus. Этот сайт документации будет иметь такие возможности, как многоязычные блоки кода и локальный поиск. Затем вы развернете сайт с помощью Netlify.

Необходимые условия

Для работы Docusaurus требуется Node.js версии 14.3 или выше. Если у вас не установлен Node.js, вы можете установить его с их сайта.

Для развертывания сайта docusaurus вам понадобятся учетные записи GitHub и Netlify. Также у вас должен быть пустой репозиторий, в котором будет храниться код вашего сайта docusaurus.

Установка проекта

Начните с создания нового проекта Docusaurus с помощью следующей команды:

npx create-docusaurus@latest my-docs classic

Это установит Docusaurus в директорию my-docs и будет использовать шаблон classic.

Теперь перейдите в каталог my-docs и запустите сервер Docusaurus:

cd my-docs
npm start

Это запустит сервер на localhost:3000 и автоматически откроет сайт в вашем браузере.

Код целевой страницы находится в src/pages/index.js. Однако в этом руководстве мы сосредоточимся только на документации.

Чтобы открыть документацию, нажмите на Tutorial в панели навигации. Вы увидите несколько страниц документации, созданных по умолчанию в Docusaursus.

Страницы документации находятся в каталоге docs вашего проекта docusaurus. Они представляют собой файлы MD или MDX. MD-файлы — это базовые файлы Markdown с синтаксисом Markdown. Файлы MDX — это файлы Markdown, которые также поддерживают синтаксис React внутри.

Попробуйте изменить содержимое intro.md на следующее:

---
sidebar_position: 1
---

# Introduction

I've changed the documentation!

Если сервер все еще работает и вы вернетесь на сайт, вы увидите, что содержимое страницы изменилось.

Обратите внимание, что в верхней части файла уценки есть три тире, за которыми следуют некоторые свойства типа «ключ-значение», а затем снова три тире. Это поля Markdown front matter, которые обеспечивают настройку некоторых атрибутов метаданных документа, таких как заголовок страницы или, в данном случае, ее положение в боковой панели.

Создание нового документа

Чтобы создать новый документ, необходимо создать новый файл в каталоге docs.

В этом разделе вы создадите MDX-файл для демонстрации и добавления некоторых возможностей MDX позже в этом учебнике.

Создайте tabs.mdx со следующим содержимым:

# How to Use Tabs

Это добавит заголовок на страницу. Если вы проверите свой сайт документации, вы должны найти новую ссылку в боковой панели для новой страницы.

Давайте изменим положение ссылки в боковой панели. Добавьте следующее в верхней части tabs.mdx:

---
sidebar_position: 2
---

Это позволит переместить «Как использовать вкладки» сразу после «Введения».

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

Этот раздел включает необязательные возможности, которые вы можете использовать в своей документации. Вы можете пропустить этот раздел или любой подраздел, если не считаете их необходимыми для себя.

Использование вкладок

Использование MDX предоставляет вам множество возможностей в ваших Markdown файлах. Одной из таких возможностей является добавление вкладок на вашу страницу.

В tabs.mdx добавьте следующее после части frontmatter, которую вы добавили ранее:

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

Затем, после заголовка страницы, добавьте следующее, чтобы добавить вкладки на страницу:

<Tabs groupId="tabs">
  <TabItem value="tab1" label="Tab 1" default>
    I like tab 1
  </TabItem>
  <TabItem value="tab2" label="Tab 2">
    I like tab 2
  </TabItem>
</Tabs>

Это добавит 2 вкладки, каждая из которых будет иметь свой текст. Обратите внимание на следующее:

1. Свойство groupId в Tabs позволяет синхронизировать выбор вкладки на всем сайте.
2. Каждый элемент вкладки должен иметь свойство value. Если вы хотите синхронизировать выбор вкладки на всем сайте, вам нужно будет использовать одно и то же значение для вкладок, используемых в других местах (пример вы увидите чуть позже).
3. Реквизит default делает вкладку выбранной по умолчанию при первом открытии страницы.

Откройте документацию, и вы увидите вкладки, добавленные в документацию. Вы можете щелкать между вкладками, и текст будет меняться.

Давайте попробуем добавить еще один компонент Tab под предыдущий:

<Tabs groupId="tabs">
  <TabItem value="tab1" label="Tab 1" default>
    I still like tab 1
  </TabItem>
  <TabItem value="tab2" label="Tab 2">
    I still like tab 2
  </TabItem>
</Tabs>

Обратите внимание, что Tabs имеет тот же groupId, что и предыдущий элемент Tabs, и элементы вкладок имеют те же значения.

Если вы откроете сайт сейчас, то увидите два компонента вкладок, каждый из которых содержит элементы вкладок и текст. Попробуйте выбрать вкладку из любого компонента, и выбор будет синхронизирован с другим компонентом вкладок.

Многоязычные блоки кода

Вы также можете использовать вкладки для добавления блоков кода с несколькими языками. Это удобно, если вы хотите показать один и тот же блок кода на нескольких языках.

Под предыдущими вкладками добавьте новый компонент вкладки:

<Tabs groupId="code-tabs">
  <TabItem value="js" label="JavaScript" default>

js
console.log(«Hello»)

  </TabItem>
  <TabItem value="python" label="Python">

py
print(«Hello»)

  </TabItem>
</Tabs>

Обратите внимание на следующее:

• Этот компонент Tabs имеет другое значение для groupId по сравнению с предыдущими вкладками. Это потому, что нет необходимости в синхронизации между этим компонентом Tabs и предыдущими компонентами.
• Блоки кода внутри вкладок должны быть окружены пустыми строками. В противном случае они не будут отображаться должным образом.
• Отступ для блоков кода не должен быть больше одной вкладки (эквивалентно 2 пробелам), иначе они могут отображаться некорректно.

Если вы откроете сайт сейчас, вы увидите вкладки для блоков кода.

Добавьте автоматические вкладки NPM и Yarn

NPM и Yarn — это распространенные менеджеры пакетов, используемые для проектов и инструментов, связанных с Node.js. Часто бывает, что вы хотите показать одну и ту же команду и в NPM, и в Yarn. Однако вручную добавлять вкладки каждый раз, когда вы хотите это сделать, довольно хлопотно.

В этом случае вы можете воспользоваться плагином npm2yarn remark. Этот плагин позволит вам автоматически преобразовать все блоки кода, использующие NPM, в yarn в вашей документации.

Начните с установки плагина npm2yarn:

npm install @docusaurus/remark-plugin-npm2yarn

Затем в docusarus.config.js нужно добавить новую опцию remarkPlugins в объект config:

const config = {
    //other options...
    presets: [
        [
          'classic',
          /** @type {import('@docusaurus/preset-classic').Options} */
          ({
              docs: {
                  //other options...
                  remarkPlugins: [
                    [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
              }
          })
        ]
    ]
};

Опция {sync: true} позволяет синхронизировать выбор пользователем вкладки по всему сайту, аналогично поведению, которое вы видели ранее с Tabs.

Теперь в tabs.mdx добавьте следующее в конце:

bash npm2yarn
npm install react

Важный бит здесь — npm2yarn. Если вы хотите, чтобы блок кода имел вкладки «npm» и «Yarn», и вы хотите преобразовать команду в yarn, добавьте это ключевое слово после первых 3 обратных знаков вашего блока кода.

Снова запустите свой сервер и откройте веб-сайт на странице документации «Как использовать вкладки». Возможно, вам потребуется выполнить жесткое обновление, чтобы очистить кэш вашего сайта.

Если вы прокрутите страницу вниз, вы увидите блок кода, который вы добавили, но с двумя вкладками «npm» и «Yarn». Вы также увидите, что команда была автоматически преобразована в команду Yarn на вкладке Yarn.

Таблица содержимого

Последняя функция, с которой вы познакомитесь в MDX файлах, это таблица содержимого. Вы можете автоматически генерировать таблицу содержимого для любой страницы.

В tabs.mdx под предыдущими импортами добавьте новый импорт:

import TOCInline from '@theme/TOCInline';

Затем добавьте следующее под заголовком страницы:

<TOCInline toc={toc} />

## Heading 2
### Heading 3

Если вы откроете сайт сейчас, вы увидите автоматически сгенерированную таблицу содержимого под заголовком на странице «Как использовать вкладки».

Обратите внимание, что компонент TOCInline будет отображать только заголовки, начинающиеся с h2 или ##. Он не будет отображать заголовки h1 или #.

Добавить поиск

Важной функциональностью в любой документации является поисковая система. В Docusaurus вы можете использовать такие сервисы, как Algolia, чтобы добавить поисковую систему. Однако в этом уроке вы добавите локальную поисковую систему, которая хорошо подходит для небольшой документации.

В терминале выполните следующую команду, чтобы установить плагин:

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

Затем в docusaurus.config.js добавьте в объект config новый ключ themes:

themes: [
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      {
        hashed: true,
      },
    ],
  ],

Это все, что вам нужно для добавления локальной поисковой системы.

Поисковая система не будет работать, если вы используете npm start. Сначала вам нужно создать сайт:

npm run build

Затем обслужить сборку:

npm run serve

Снова откройте веб-сайт на localhost:3000. Вы должны увидеть строку поиска справа от панели навигации.

Попробуйте найти одну из добавленных вами страниц, и вы увидите результаты в выпадающем списке.

Настройка боковой панели

В настоящее время боковая панель генерируется автоматически из файлов в каталоге docs. Однако вы можете вручную настроить боковую панель и элементы в ней.

Для этого откройте файл sidebars.js и измените значение объекта sidebars на следующее:

const sidebars = {
   tutorialSidebar: [
        {
          type: 'doc',
          id: 'intro'
        },
        {
          type: 'category',
          label: 'Tutorial',
          items: [{
            type: 'doc',
            id: 'tabs',
            label: 'Learn all about tabs'
          }],
        }
    ]
};

Это изменит боковую панель на ссылку и сворачиваемый раздел с одним подпунктом.

Если вы сейчас откроете сайт, то увидите, что боковая панель изменилась.

Изменение ссылки «Редактировать эту страницу»

В конце каждого документа вы найдете ссылку «Редактировать эту страницу». Это позволяет участникам легко вносить изменения, которые они считают необходимыми, и отправлять PR в ваш репозиторий.

Префиксный URL этой страницы задается в docusaurus.config.js в объекте docs в массиве presets в объекте config:

docs: {
    editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
    },

Вы должны изменить это на каталог docs вашего репозитория. Например:

"https://github.com/shahednasser/docusaurus-tutorial/tree/master/"

Префикс URL должен быть URL до того, как вы попадете в каталог docs.

Вы можете проверить это, зафиксировав изменения и перенеся их в репозиторий. Затем попробуйте щелкнуть ссылку на любом из документов, и откроется новая страница. Это будет документ на GitHub, где вы сможете отредактировать его и отправить PR с изменениями.

Развертывание веб-сайта документации

Последний шаг — развертывание веб-сайта документации. Войдите в Netlify, затем нажмите на «Добавить новый сайт» и из выпадающего списка выберите «Импортировать существующий проект».

Откроется новая страница для создания нового сайта. Вы можете выбрать импорт кода с нескольких сайтов, включая GitHub. Нажмите на GitHub.

Затем вам будет предложено предоставить Netlify права доступа к вашей учетной записи GitHub, если вы не сделали этого раньше.

После того как вы предоставите необходимые разрешения, вы сможете выбрать хранилище для развертывания. Выберите хранилище, которое вы создали для сайта docusaurus.

На следующей странице Netlify покажет настройки сборки и развертывания. Они должны быть похожи на следующие:

Если все выглядит хорошо, нажмите «Развернуть сайт». Netlify создаст и развернет ваш сайт, что займет пару минут.

После развертывания и публикации вы сможете получить доступ к сайту со случайно сгенерированного доменного имени. Вы можете найти его в верхней части приборной панели вашего сайта в Netlify.

Если вы откроете свой сайт, то обнаружите, что он полностью аналогичен тому, над которым вы работали локально, и все функции работают хорошо.

Заключение

В этом руководстве вы узнали о различных функциях документации Docusaurus, о том, как добавить локальный поиск, и как развернуть сайт на Netlify.

Вам еще многое предстоит сделать с вашей документацией. Вот некоторые дополнительные шаги, которые вы можете предпринять:

1. Узнайте, как настроить доменное имя в Netlify.
2. Узнайте, как управлять страницами и блогом вашей документации.
3. Ознакомьтесь с документацией Docusaurus, чтобы узнать обо всех возможностях, которые вы можете добавить в свою документацию.