Starlight
Тема для движка Astro
| Версия | 0.42.6 |
|---|---|
| Проверено | 2026-10-16 |
| Готовность для мультиязычного проекта | вики 64 % проверено 15 из 31 сайт 70 % проверено 16 из 34 как считается |
| Мнение автора | не выберу Из заметок: «разочарован в Astro Starlight в первую очередь в архитектуре мультиязычности». Вторая попытка 2026-10-16 (перенос вики с Hugo) — тоже отказ, сайт делается на Hugo + Hextra. (2026-10-16) |
| Цена | бесплатно |
| Лицензия | MIT |
| Репозиторий | https://github.com/withastro/starlight |
| Демо | https://starlight.astro.build |
| CSS | Собственные стили темы на CSS-переменных; Tailwind не обязателен |
| JavaScript | Компоненты Astro; в браузер отправляется минимум JavaScript |
| Node.js | Нужен Node.js для разработки и сборки; на сервере — только готовые HTML/CSS/JS |
| Переводы интерфейса | Готовые переводы интерфейса, в том числе en, ru, uk, pt |
Поиск по сайту
Полнотекстовый поиск прямо в браузере на Pagefind. Сервер, база данных и внешние сервисы не нужны, ключи не требуются.
| Где работает | в браузере посетителя (JavaScript) |
|---|---|
| На чём построен | Pagefind — инструмент статического поиска: после сборки сайта проходит по готовым HTML-страницам и строит индекс, а в браузере ищет его небольшая JavaScript-часть. |
| Откуда берёт тексты | Индекс создаётся при сборке и разбит на мелкие части: браузер скачивает только нужные. По данным Pagefind, на сайте в 10 000 страниц поиск обычно стоит меньше 300 КБ трафика. |
| Языки | Для каждого языка свой индекс, ищет на языке текущей страницы. Формы слов Pagefind понимает для русского и португальского, для украинского — нет (ищет только по началу слова). Результаты можно фильтровать по разделам и тегам. |
| Проверено | 2026-10-16 |
Плюсы
- Удобная навигация документации: боковое меню, поиск и оглавление из коробки.
- Готовые компоненты: вкладки, карточки, пошаговые инструкции, предупреждения, дерево файлов, карточки-ссылки.
- Поиск Pagefind: индекс делится на части, поэтому подходит и для очень больших сайтов.
- Основной язык можно держать в корне без /en/; есть языковые каталоги и переключатель языков.
- Перелинковку в стиле DokuWiki (
[[страница]]) можно добавить своим плагином; в Astro 7 remark-плагины (remark-wiki-link) с процессором по умолчанию не работают. - Есть признак isFallback: страницы без перевода можно найти и закрыть от индексации централизованно.
Минусы
- Архитектура мультиязычности: слишком много ручной работы, чтобы свести вместе меню, поиск, оформление и SEO-правила для нескольких языков.
- Переключатель показывает все языки сайта, даже если у страницы нет перевода: со статьи только на ru ведёт на несуществующие страницы (404).
- hreflang в head ссылается и на страницы без перевода (в sitemap при этом всё верно).
- Свой адрес у перевода (slug) рвёт связь переводов: адрес должен совпадать во всех языках.
- Нет разметки Schema.org и хлебных крошек.
- Темы оформления, которые заменяют компоненты Starlight (Nova и др.), ломают её: годятся только темы с одним CSS.
- Если перевода нет, на адресе другого языка показывается текст на основном языке — для SEO нежелательно.
- Mermaid и формулы KaTeX не встроены — подключаются отдельными интеграциями.
Общее впечатление
Тема для документации на Astro. Проверялась дважды, оба раза отказ.
В сентябре 2026 (по заметкам): «разочарован в Astro Starlight в первую очередь в архитектуре мультиязычности». 2026-10-16 на Starlight 0.42.6 перенесли всю вики dieg.net с Hugo; доработки выше сделаны в этом проекте. Меню языков и hreflang так и остались со ссылками на несуществующие переводы — чинить их пришлось бы заменой компонентов Starlight. Сайт делается на Hugo + Hextra.
Что пришлось доработать
Вставка файла скрипта в статью
| Проблема | Скрипты лежат файлами (wget -qO- https://dieg.net/scripts/x.sh | bash), а в статье нужен тот же код блоком. |
|---|---|
| Что сделано | Свой плагин Sätteri: ::local-gist{file="scripts/x.sh" lang="bash"} превращается в блок кода с именем файла и ссылками Raw / Download. |
| Файлы | src/plugins/local-gist.mjs astro.config.mjs |
| Объём работы | средний |
Внешние ссылки в новом окне
| Проблема | Встроенной настройки нет. |
|---|---|
| Что сделано | Свой плагин Sätteri добавляет target="_blank" rel="noopener noreferrer" ко всем ссылкам на чужие сайты. |
| Файлы | src/plugins/external-links.mjs |
| Объём работы | небольшой |
Светлая тема по умолчанию
| Проблема | Starlight по умолчанию берёт тему из настроек системы. |
|---|---|
| Что сделано | Одна строка-скрипт в head в astro.config.mjs: если читатель тему не выбирал, ставится светлая. |
| Файлы | astro.config.mjs |
| Объём работы | небольшой |
Цвета Gruvbox без замены компонентов
| Проблема | Плагин темы starlight-theme-gruvbox сам задаёт обе схемы блоков кода и затирает настройки; заявлен для Starlight 0.38. |
|---|---|
| Что сделано | Подключён только его CSS в customCss и тёмная схема кода в expressiveCode.themes; совместимость — секцией overrides в package.json. |
| Файлы | astro.config.mjs package.json |
| Объём работы | небольшой |
Результаты по требованиям с этой темой
| Требование | Результат | От чего зависит | Примечание |
|---|---|---|---|
| Мультиязычность | |||
Материал можно начать на неосновном языке ml-author-any-lang | да | тема | статья только на ru собирается без заглушки en |
Переключатель языков показывает только существующие переводы ml-switcher-existing | нет | тема | на статье только на ru меню языков ведёт на /guides/lemp/, /uk/…, /pt/… — таких страниц нет (404) |
hreflang только на существующие переводы ml-hreflang-existing проверить ↗ | нет | тема | hreflang в head на все 4 языка и x-default, даже без перевода — ссылки на 404. В sitemap при этом alternate верные |
Нет автостраниц с контентом основного языка ml-no-fallback-pages проверить ↗ | нет | тема | по коду Starlight (utils/routing): для страницы основного языка без перевода создаётся страница с английским текстом и плашкой; в этой сборке не проявилось — все en-страницы переведены |
Основной язык в корне, остальные с префиксом ml-default-root | да | тема | locale root = en без префикса, uk/ru/pt — /uk/ /ru/ /pt/ |
У каждого перевода свой slug ml-translated-slugs | нет | тема | свой slug меняет ID записи и рвёт связь переводов (меню языков, hreflang) — проверено в проекте |
Атрибут lang в нужном формате ml-html-lang | да | тема | html lang = ru, uk, pt-BR |
Переводы интерфейса для en, uk, ru, pt-BR ml-ui-strings | да | тема | переводы интерфейса есть для uk, ru и pt (бразильский: «Pular para o conteúdo») |
| Статьи, навигация и поиск | |||
Поиск по сайту site-search | да | тема | Pagefind строится при сборке, отдельный индекс на язык (en, uk, ru, pt-br), ищет на языке страницы; формы слов для ru и pt понимает, для uk — нет |
Подсветка кода code-highlight | да | тема | Expressive Code: заголовок блока, кнопка копирования |
Пошаговые инструкции content-steps | да | тема | компонент Steps (только в .mdx); есть Tabs, Aside, Card, FileTree |
| SEO | |||
sitemap с языковыми версиями seo-sitemap | да | плагин | @astrojs/sitemap: alternate только на существующие переводы |
Корректный canonical seo-canonical проверить ↗ | да | тема | canonical на саму страницу |
Микроразметка schema.org seo-schema | нет | тема | JSON-LD и хлебных крошек нет |
| Хранение и окружение | |||
Работает без сервера БД no-db | да | движок | статическая сборка, контент в Markdown |
Работает в окружении Nginx + PHP-FPM 8.5 runtime-php | да | движок | nginx отдаёт dist/; php-fpm 8.5 только для своего excuse.php |