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

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

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

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

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

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

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

тесты на экологичность по количеству выбросов CO2 на посещение страницы

Настало время ускорить сборку, облегчить картинки и написать пару 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. В репозитории можешь посмотреть как это сделать, здесь напишу только куда смотреть:

файл конфигурации сборки .github/workflows/astro.yml (у меня стоит ветка master, обрати внимание)
в astro.config.mjs надо поменять папку выхода с dist на _site

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

Finale

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

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