F-13 Docs site — Astro Starlight standalone

Контекст

Phase 1 Foundation: после F-12 (admin panel done), нужен standalone documentation site на docs.razmakh.ru для трёх аудиторий (партнёры, разработчики, on-call). Decision AK + sync decision: Astro Starlight 5.x + Pagefind (sanctions-safe vs Algolia), standalone build, не shared с Next.js apps/web.

Что сделано

Создан полноценный apps/docs/ workspace package в monorepo:

Стек: Astro 5.18.1 + Starlight 0.30.6 + Pagefind built-in
Контент: ru default, 4 аудиторных раздела (users / devs / architecture / runbooks / lessons), 17 lessons + 2 architecture pages синхронизируются на build time из repo source files (single source of truth)
Тема: brand tokens из F-11 reused 1:1 — --sl-color-accent = oklch(0.62 0.13 65) (тёплая охра), warm cream light + warm graphite dark, Manrope (body) + Lora (headings serif) + JetBrains Mono (code)
Pagefind: built-in static search (sanctions-safe), 5070 слов indexed
Deploy: Docker container razmakh-docs (nginx alpine + static dist/), Caddy reverse_proxy на docs.razmakh.ru через DNS-01 TLS
CI: Stage 5.5 docs-build через dorny/paths-filter@v3 — runs только если изменились apps/docs/, lessons/, docs/architecture/, lockfile; не blocking other stages

Как сделано

Sync-lessons script (`apps/docs/scripts/sync-lessons.mjs`)

3 источника: lessons/*.md, docs/architecture/*.md, $RAZMAKH_NETNIK_STATE_DIR/runbooks/razmakh-*.md
Старый frontmatter преобразуется в Starlight-compliant (title, description, sidebar.order, lastUpdated)
draft: true skipped, README/TEMPLATE skipped
Build-time invocation (часть pnpm build), не commit’ится в git

`.gitignore` anchoring (Lesson `git-tracking-after-agent-code` repeat-applied)

Astro builds в apps/docs/dist/ и apps/docs/.astro/. Существующий root .gitignore имел unanchored build/ + dist/ patterns — потенциальный риск (те же что Python). Поправил: /build/ + /dist/ anchored to repo root. Также явно excluded apps/docs/dist/, .astro/, и sync-output paths + allowlist index.md placeholders. Verified: git add apps/docs/ → 19 files staged, all source artifacts; sync output filtered correctly.

MDX strict parser quirk

Astro 5 MDX parser обрабатывает <http://localhost:3000> как raw JSX — ломается build:

Unexpected character `/` (U+002F) before local name, expected a character that
can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX,
use `[text](url)`)

Fix: использовать markdown link syntax [label](url) вместо bare URL в угловых скобках. CommonMark autolinks работают в .md, но не в .mdx.

`social:` config breaking change

Starlight 0.30 ожидает social: { github: "..." } (object), не array. Старый formatter — array of objects — был для 0.32+. Pinned 0.30.6 — нужен object. Caught via astro check.

Что улучшено / что отвергнуто и почему

Альтернатива	Почему отвергнуто
Cloudflare Pages (был в plan)	razmakh-vps + Caddy уже есть; одна точка failure, простой deploy
Algolia search	Sanctions-risk для РФ-юрлица; Pagefind static — owned
MkDocs / Docusaurus	AK §16 decision — Starlight wins (Pagefind, MDX, builds, i18n)
Symlink lessons вместо sync script	Docker COPY не follow symlinks через monorepo boundary
Inline content в apps/docs/src/content/docs/	Duplication = drift; build-time sync = single source of truth

Lesson learned

В контексте Astro 5 MDX в pnpm monorepo с custom build pipeline — bare-URL autolinks <https://...> ломают MDX parser (отличие от vanilla markdown). Всегда [label](url) syntax. Catches via astro check до build.

В контексте multi-language repo (Python + Node + Astro) — .gitignore patterns должны быть anchored к root (/build/, /dist/), иначе они greedy-match вложенные dirs в apps/*. Lesson F-11 (lib/ → /lib/) повторно применился здесь. Verify через git ls-files + git check-ignore -v сразу после первого Write.

В каких будущих ситуациях пригодится

Phase 1.5: добавление новых lessons + architecture decisions — auto-sync.
Phase 2: i18n EN content — config готов (locales: { ru, en }).
Phase 3 SaaS: docs.razmakh.ru останется бесплатным public, продуктовый in-app help уйдёт на help.razmakh.ru (sep poddomain — см. AK §1.7).
F-14 release-please: CHANGELOG автообновляется, Astro Starlight подхватит через sync — нужно дополнить sync-lessons.mjs (или второй script) для CHANGELOG.md → docs/release-notes/.
F-15+: при добавлении новых subdomains (Grafana, GlitchTip уже есть) — pattern Caddy reverse_proxy установлен.

Связанные lessons / decisions

[[razmakh-docs-platform-astro-starlight-2026-05-17]] — выбор stack
[[f11-frontend-skeleton-2026-05-17]] — brand tokens source (re-use)
[[f11-build-debugging-2026-05-18]] — Docker monorepo build pitfalls (apply same)
[[git-tracking-after-agent-code]] (Claude agent memory) — .gitignore re-application