Фреймворк Astro: Установка на Linux/Windows 11 и настройка Starlight

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

Astro был разработан для создания сайтов с большим количеством контента. Сюда входят маркетинговые сайты, издательские сайты, сайты документации, блоги, портфолио, целевые страницы, сайты сообществ и сайты электронной коммерции. Ориентация Astro на контент с самого начала его существования как конструктора статических сайтов. Чтобы ваш Astro проект отображался в браузере, его код должен быть преобразован в HTML.

Особенности Astro:

• Без UI-ограничений, поддерживает React, Preact, Svelte, Vue, Solid, Lit, HTMX, веб-компоненты и многое другое.
• Islands architecture (Островки). Компоненты Astro — это строительные блоки шаблона вашей страницы. Они рендерятся в статический HTML без клиентского выполнения. По умолчанию Astro автоматически переводит каждый компонент UI в HTML и CSS, убирая весь JavaScript на стороне клиента.
• Язык .astro — это надмножество HTML: любой допустимый HTML допустим в синтаксисе шаблонов Astro! Так что, если вы можете писать HTML, то вы можете писать компоненты Astro!
• Официальное расширение для VS Code с подсветкой синтаксиса.

Astro использует серверный рендеринг вместо клиентского рендеринга в браузере в максимально возможной степени. Это тот же подход, который традиционные серверные фреймворки – PHP, WordPress, Laravel, Ruby on Rails и т. д. – используют уже десятилетия. Но вам не нужно изучать второй серверный язык, чтобы использовать его. С Astro всё по-прежнему сводится к HTML, CSS и JavaScript. Чтобы рендерить страницы по запросу, вам нужно подключить адаптер. Каждый адаптер позволяет Astro сгенерировать скрипт, запускающий ваш проект в конкретной среде выполнения — окружении, которое выполняет код и генерирует страницы при обращении к ним (например, Cloudflare).

Мультиязычность (i18n) Astro поддерживает из коробки. Есть встроенная i18n-маршрутизация: языки, язык по умолчанию, URL вида /en/…, /ru/…, fallback и т. п. Отдельный i18n-плагин не нужен. Официальную документацию смотрите в разделе Многоязычная маршрутизация (i18n).

Если перевод для языка ещё не доступен, Astro Starlight покажет читателям контент этой страницы на языке по умолчанию (установленном через defaultLocale). Например, если вы ещё не создали французскую версию вашей страницы «О нас» и вашим языком по умолчанию является английский, посетители /fr/about увидят английский контент из /en/about с уведомлением о том, что эта страница ещё не была переведена. Это помогает вам добавлять контент на вашем языке по умолчанию и постепенно переводить его, когда у ваших переводчиков есть время.

Прочитали, кажется, всё хорошо? Представим себе ситуацию, что какую-то статью нужно перевести только на часть языков, а на остальные нет. Но мы автоматически получаем в переключателе языков список всех языков сайта (а не только где есть перевод), но это полбеды, хуже всего параметр hreflang в микроразметке сайта будет показывать и на страницы без перевода. Для примера в архитектурном решении у Hugo такой проблемы вообще нет.

Astro создан на основе Vite, который по умолчанию нацелен на браузеры с современной поддержкой JavaScript. Доступна русскоязычная официальная документация Установка и настройка Astro.

• Node.js - v18.17.1, v20.3.0, v22.0.0, или выше (v19 и v21 не поддерживаются). Node.js требуется только для разработки и сборки, в production Node.js-сервер не нужен. Результат — обычные статические HTML/CSS/JS-файлы, которые можно отдавать через Cloudflare Pages или Nginx.
• Текстовый редактор - Мы рекомендуем VS Code с нашим официальным расширением Astro.
• Терминал - Доступ к Astro осуществляется через интерфейс командной строки (CLI).

Мое рабочее окружение Linux обычно с Xfce, поэтому сначала смотрим что версии ПО:

$ git --version
git version 2.43.0
$ npm -v
11.6.2
$ node -v
v24.12.0
$ nvm ls
->     v24.12.0
         system
default -> lts/* (-> v24.12.0)
...
lts/krypton -> v24.12.0
darkfire@dark:~$

И я вижу, что мое системное оружение полностью соответствуете всем требованиям для Astro, в частности, установлена последняя официальная LTS-версия Node.js.

В первую очередь нужно проверить системное окружение на вашем Windows 11, поэтому запускаем PowerShell (основной инструмент системного администрирования вместо cmd). Cмотрим что у меня установлено и какие версии у ПО, если чего то нет устанавливаем.

• Перейдите на официальный сайт nodejs.org и скачайте версию LTS.

PS C:\Users\darkfire> node -v
v25.4.0

• а вот дальше с npm ошибка. Ошибка npm (UnauthorizedAccess): Это стандартная политика безопасности Windows PowerShell, которая по умолчанию запрещает запуск сторонних .ps1 скриптов.

PS C:\Users\darkfire> npm -v
npm : Невозможно загрузить файл C:\Program Files\nodejs\npm.ps1, так как выполнение сценариев отключено в этой
системе. Для получения дополнительных сведений см. about_Execution_Policies по адресу
https:/go.microsoft.com/fwlink/?LinkID=135170.
строка:1 знак:1
+ npm -v
+ ~~~
    + CategoryInfo          : Ошибка безопасности: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

Исправление ошибки запуска npm (Разрешает запуск npm в PowerShell).
Откройте PowerShell от имени Администратора (нажмите Win, введите PowerShell, нажмите правой кнопкой → Запуск от имени администратора) и выполните команду:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

На запрос ответьте Y (Yes) и нажмите Enter. После этого проверьте работу npm и у меня заработало:

PS C:\Users\darkfire> npm -v
11.7.0

Если Git не установлен, скачайте и установите его с официального сайта git-scm.com. При установке я оставил все компоненты по умолчанию, как показано на скриншоте. На следующем экране мастера установки, убедитесь, что выбрана опция «Git from the command line and also from 3rd-party software» для корректного добавления git в переменную PATH. После установки перезапустите PowerShell и проверьте:

PS C:\Users\darkfire> git --version
git version 2.55.0.windows.5

На этом этапе, я вижу, что все мое системное окружение Windows 11 полностью соответствуете всем требованиям для Astro.

В Linux все просто, а вот для Windows 11 есть рекомендации.

В каталоге:

cd ~/projects

Создадим проект. create-astro это CLI-мастер установки и у него собственный цикл релизов и своя нумерация. В итоговом файле package.json созданного проекта в секции dependencies будет указан именно astro: "^7.2.0".

$ npm create astro@latest
Need to install the following packages:
create-astro@5.2.4
Ok to proceed? (y) 

Например в директорию project_zones:

Where should we create your new project?
./project_zones

Для первого проекта выбирать максимально простой вариант:

 tmpl   How would you like to start your new project?
         ○ A basic, helpful starter project (recommended)
         ○ Use blog template 
         ● Use docs (Starlight) template 
         ○ Use minimal (empty) template 

Если мастер предлагает установить зависимости, выбираем Yes. Git: Yes.

После создания, командой npm run dev запускаем сервер разработки. Сочетание клавиш q + ENTER останавливаем сервер:

cd project_zones
npm run dev

Astro покажет локальный URL примерно:

http://localhost:4321/

Лучшее место: Отдельная папка для разработки, например:

• C:\Projects\project_dnet
• C:\Dev\project_dnet
• D:\Projects\project_dnet (если есть второй диск)

Запускаем PowerShell и начинаем колдовать:)

mkdir C:\Projects
cd C:\Projects

Запускаем мастер создания Astro с шаблоном Starlight

npm create astro@latest -- --template starlight project_dnet

На скриншоте видно какие параметры я выбирал и видим что проект project_dnet создался успешно.

Проще всего открывать проект в VS Code из консоли Linux, Windows в директории проекта вводя команду:

cd project_dnet
code .

Установка плагина Astro:

В VS Code установите официальное расширение Astro (astro-build.astro-vscode) от разработчиков Astro, как показано на скриншоте. В открывшемся VS Code нажмите Ctrl + Shift + X (откроется панель расширений). В поиске введите Astro (ID: astro-build.astro-vscode). Нажмите Install. Для первого этапа базового плагина Astro действительно более чем достаточно — он сразу даст подсветку синтаксиса .astro файлов, автодополнение и поддержку TypeScript. Что бы при каждом сохранении (Ctrl + S) VS Code сам выравнивал отступы и HTML-теги в .astro файлах, используя движок встроенного плагина, нужно создать файл .vscode/settings.json в корне вашего проекта и добавьте текстовую инструкцию в формате JSON:

{
  "editor.formatOnSave": true,
  "[astro]": {
    "editor.defaultFormatter": "astro-build.astro-vscode"
  }
}

1. Внутри VS Code откройте встроенный терминал с помощью комбинации клавиш Ctrl + ~ (или через меню Terminal → New Terminal).
2. Запустите сервер разработки:

   npm run dev

   В терминале появится адрес: http://localhost:4321/.

Нажмите Ctrl и кликните по этой ссылке в терминале — ваш новый проект откроется в мини-браузер (Simple Browser), который встроен в VS Code! Как его настроить читайте в разделе Настройка мини-браузер встроенного в VS Code.

Чтобы Astro не отправлял анонимную статистику использования, прямо во встроенном терминале VS Code нажмите Ctrl + C (остановит dev-сервер) и выполните:

npx astro telemetry disable

После этого снова запустите сервер:

npm run dev

Проект полностью запущен и готов к настройке.

Темы в Astro есть, но я бы для такого pSEO-проекта не ставил готовую тему на старте. Не потому что Astro «красивый из коробки» — он практически ничего не оформляет. Просто тебе нужны Header + Footer + нормальная типографика + таблицы + карточки. Это проще сделать самому, чем потом разбирать чужую тему с десятками ненужных компонентов. Если найдём действительно простую подходящую тему — использовать можно.

Starlight лучше всего соединяет два разных типа контента:

• обычные статьи в Markdown/MDX;
• программно сгенерированные справочники из JSON;
• интерактивные таблицы, фильтры и калькуляторы на Native JS;
• перелинковка и Вики-фичи: Подключается плагин remark-wiki-link для синтаксиса

  [[page-name]]

  как в DokuWiki;

• встроен локальный быстрый поиск Pagefind (не требует внешних сервисов и ключей);
• Темы для Starlight от сообщества
• документационную навигацию, поиск и оглавление.

Starlight официально поддерживает корневой язык без /en/, языковые каталоги, переключатель языков и готовые переводы интерфейса, включая EN, RU, UK, PT, ES, ID и VI.

Важное ограничение: если перевода нет, Starlight может создать локализованный URL с английским содержимым. Для SEO это нежелательно. Поэтому я бы:

• генерировал pSEO-страницы только для языков, где реально есть локализованные данные;
• для fallback-страниц автоматически добавлял noindex и canonical на английскую страницу;
• не подключал новый язык только ради пустого переключателя.

Starlight предоставляет признак isFallback, поэтому такую проверку можно сделать централизованно.

Для обычных статей работает схема:

---
title: HTTP status 404
draft: true
---

Такие страницы доступны при локальной разработке, но исключаются из production build, поиска и автоматической навигации. Для pSEO-записей можно использовать собственное поле в JSON:

{
  "code": 404,
  "status": "draft",
  "last_verified": "2026-08-20"
}

И фильтровать записи внутри getStaticPaths().

Starlight использует Pagefind. Это статический поиск без отдельного сервера: индекс создаётся во время сборки и разбивается на части. Pagefind ориентирован на сайты с десятками тысяч страниц; для сайта на 10 000 страниц заявлен поисковый трафик обычно менее 300 КБ. Он также понимает языки и может фильтровать результаты по разделам и тегам.

Starlight уже содержит:

• вкладки;
• карточки;
• пошаговые инструкции;
• предупреждения;
• дерево файлов;
• кнопки и внутренние карточки-ссылки.

Mermaid и KaTeX не являются основной встроенной функцией Starlight, но подключаются через Markdown-интеграции. Asciinema можно оформить одним Astro-компонентом. Перелинковка как в DokuWiki: подключается плагин remark-wiki-link для синтаксиса:

[[page-name]]

<slot />

— это место, куда Astro вставляет содержимое конкретной страницы. Это стандартный механизм layouts в Astro.

Файл .gitignore, который создаётся по умолчанию, уже полностью правильный и содержит 95% всего необходимого. Стандартного содержимого от Astro вполне достаточно, но для чистоты репозитория и предотвращения утечек ключей его стоит немного дополнить.

Итоговый рекомендуемый .gitignore для Astro:

# build output
dist/
 
# generated types
.astro/
 
# dependencies
node_modules/
 
# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
 
# environment variables
.env
.env.*
!.env.example
 
# macOS-specific files
.DS_Store
 
# IDEs and Editors
.idea/
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
*.suo
*.ntvs*
*.njsproj
*.sln
 
# Local temp & swap files
*.swp
*.swo
 
# Temporary & cache folders
.cache/
tmp/