Недавно у меня была задача — нужно было сделать сайт документации для одного проекта. Хочу поделиться удобным инструментом для этого, пока готовлю продолжение по jwt.
🦖А поговорим мы про Docusaurus! Это опенсорс-фреймворк от Meta, который позволяет быстро развернуть сайт документации.
Идея Docusaurus заключается в том, чтобы писать документацию с использованием Markdown и MDX на основе React. Такое сочетание позволяет легко создавать как обычные страницы, так и интерактивный контент — например, вставлять компоненты прямо в документацию.
Основные возможности:
✔️ Основан на React, поэтому все легко кастомизировать
✔️ Есть готовые темы и поддержка Markdown, чтобы писать проще и быстрее
✔️ Простая интеграция с GitHub Pages или любым хостингом
✔️ Много фич «из коробки»: поиск, версионирование, темная тема
✔️ Поддерживает миграцию
Как работать с Docusaurus?
Давайте быстренько пройдемся по шагам. Для начала вам нужно создать Docusaurus-проект в вашем репозитории. Для этого (после установки Node.js) запустите:
npx create-docusaurus@latest my-website classic
В результате у вас появится примерно такая структура:
my-website
├── blog
├── docs
├── src
├── static
├── docusaurus.config.js
├── package.json
└── sidebars.js
Ключевые каталоги:
▫️blog/ — записи блога, которые можно писать на Markdown или MDX
▫️docs/ — ваши файлы документации
▫️src/ — кастомные компоненты, страницы и стили на React
▫️static/ — статические ресурсы, например картинки и шрифты
▫️docusaurus.config.js — главный файл конфигурации сайта
▫️sidebars.js — настройка боковой панели и структуры документации
Запуск и публикация
Чтобы посмотерть, что у вас получилось:
1. Установите зависимости:
npm install
2. Запустите локальный сервер разработки:
npx docusaurus start
Сайт будет доступен по адресу:
http://localhost:3000. Все изменения в *
.md-файлах или компонентах будут применяться мгновенно благодаря горячей перезагрузке.На этом этапе ваш сайт уже работает — осталось лишь наполнить его контентом и опубликовать.
Далее все зависит от ваших умений.
✔️ Хотите полноценный сайт с главной страницей, кастомными компонентами и выпадающими окнами? Используйте React/JS/TS и расширяйте проект
✔️ Нужна просто документация? Достаточно оформить всё в
.md-файлах в docs — роутинг создаётся автоматически (можно и вручную)Для публикации ващего сайта вам нужно будет запустить команду:
npm run build
В папке
build появятся статические файлы, которые можно развернуть на любом хостинге.Чтобы убедиться, что все работает так, как задумано, протестируйте сборку локально, выполнив следующую команду:
npm run serve
Это запустит локальный сервер, и вы сможете просматривать свой сайт, перейдя по указанному URL.
Развернуть сайт можно где угодно: GitHub Pages, Vercel, Netlify, Docker + собственный домен.
В итоге с Docusaurus можно буквально за пару часов поднять удобный и красивый сайт документации, который легко поддерживать и расширять🙌