Ускоряем документацию в 10 раз

Чтобы загрузить документацию docusaurus необходимо 2 мегабайта JavaScript’а. Это же обычный статический сайт! В моём неожиданном сайд-квесте избавиться от реакта, решил убрать его с jakeloud.com — документации небольшого CI/CD инструмента.

Дизайн — последнее, что меня волнует в технической документации. Главное, чтобы было удобно пользоваться и было легко донести информацию.

Преимущества starlight перед docusaurus

Starlight — коробочное решение для документации, которое использует astro вместо react. Для astro характерна архитектура «islands», которая загружает не весь JS, а только тот, что нужен для отображения динамических элементов. Генерация происходит в момент сборки.

И более того, можно использовать react внутри astro, для этого достаточно установить официальный плагин. Astro — framework-agnostic.

Именно перед docusaurus у starlight есть набор преимуществ, о которых нельзя ни сказать:

1. автоматически генерируется индекс для поиска по сайту при помощи pagefind (всё уже настроено для тебя)

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

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

Настало время ускорить сборку, облегчить картинки и написать пару markdown файлов.

Но перед тем как получить ценность, хочу упомянуть, что уже более полугода каждый день пишу о своём пути к principal swe вот тут: https://t.me/fearorlove7734

Миграция текстов и картинок

В docusaurus у тебя была папка docs в корне проекта. Там лежали markdown файлы, сгруппированные по категориям. А картинки лежали внутри папки static (и/или public). Эти две папки надо будет сохранить.

И уже на этом этапе видно неидеальность docusaurus: картинки просто копируются в результирующую сборку, к ним не применяются никакие оптимизации.

Для начала надо создать новый astro проект с шаблоном starlight (для документации):

npm create astro@latest -- --template starlight

Далее копируем папку docs внутрь src/content/docs/ , но лучше оставить index.mdx, который там изначально лежал — он описывает главную страницу, а не страницу документации. Картинки можно временно вставить в public.

Если проделать эти шаги, проект перестанет собираться, потому что astro поддерживает статическую типизацию frontmatter контента внутри markdown, и скорее всего, до этого в контенте не были указаны обязательные поля.

Изменения контента

Первое что нужно сделать — проставить title в frontmatter в каждом markdown файле документации. Title будет оторбажаться в сайдбаре и в заголовке, а также в title браузера. Пример:

--- title: Jakeloud intro sidebar:   order: 1 ---  Let's discover **Jakeloud in less than 5 minutes**. 

Здесь я ещё добавил sidebar.order, потому что в моей документации важен порядок, в котором надо показывать страницы.

Дополнительно можно вставить в mdx разнообразные компоненты. Например, Steps, более красивый ordered list:

Дальше нужно сконфигурировать сайдбар. Для этот надо поменять в конфигурации поле sidebar. Можно вручную добавлять каждую статью или позволить starlight самому сгенерировать из всех имеющихся файлов, как я поступил:

sidebar: [   {     label: 'Guide',     autogenerate: { directory: 'guide' },   },   {     label: 'Experimental features',     collapsed: true,     autogenerate: { directory: 'experimental' },   }, ],

Наконец, надо решить вопрос с картинками. Для этого все, что рисуются только в контенте документации переносим в src/assets, меняем все ссылки на них в стиль @/assets/img.png и надо ещё добавить этот алиас в tsconfig.json:

"compilerOptions": {     "baseUrl": ".",     "paths": {       "@/*": [         "./src/*"       ]     }   }

Теперь картинки будут автоматически перегоняться в webp формат при компиляции, что экономит дисковое пространство и ускоряет сайт.

Кастомизация

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

Также надо добавить логотип и фавикон в astro.config.mjs. Это делается предельно просто.

И ещё, starlight поддерживает все параметры astro, в том числе редиректы. И мне как раз надо было установить пару редиректов для скриптов установки инструмента.

Главная страница

На предпоследнем шаге миграции вернёмся к файлу index.mdx, который отложили в начале.

Там можно поменять ссылки и action’ы (кнопки) внутри frontmatter, наполнить контентом карточки с преимуществами и что-то ещё:

--- title: Jakeloud description: self-hosted heroku alternative template: splash hero:   tagline: self-hosted heroku alternative   actions:     - text: Jakeloud Tutorial - 5min ⏱️        link: /guide       icon: right-arrow ---  import { Card, CardGrid } from '@astrojs/starlight/components'; ...

Кстати, в starlight встроена библиотека с svg иконками, которые можно вставлять в пользовательские компоненты. И в моём примере видно иконку right-arrow.

Наконец, можно переопределять существующие компоненты. Так я переопределил hero-секцию. Для этого уже понадобится минимальное знание работы astro, но если тебе интересно, можешь посмотреть как тут.

Бонус: деплой

Большой плюс astro по сравнению с react в скорости компиляции. Значит, будет затрачено немного ресурсов и можно воспользоваться GitHub Actions. В репозитории можешь посмотреть как это сделать, здесь напишу только куда смотреть:

1. файл конфигурации сборки .github/workflows/astro.yml (у меня стоит ветка master, обрати внимание)

2. в astro.config.mjs надо поменять папку выхода с dist на _site

И для традиционного случая можно собрать и задеплоить в докере с nginx. Смотри nginx.conf и Dockerfile в репозитории.

Finale

Всем бб, всем гг. Ещё раз https://t.me/fearorlove7734