How to publish to docs.ragdoll-labs.com

Portfolio Site Sync Guide

Як редагувати документацію портфоліо-сайту і контролювати, що публікується. Live: https://docs.ragdoll-labs.com/ Repo: Panda-Sensei-1584/portfolio-site (private; Cloudflare Pages деплой з master) Last updated: 2026-05-03

Архітектура

┌──────────────────────────────────────────────────────────────┐
│  Obsidian: ~/Obsidian/portfolio-site/                        │
│  (це symlink → ~/dev/portfolio-site/vault/, реальні файли    │
│   живуть у git-репо)                                          │
└────────────┬─────────────────────────────────────────────────┘
             │ редагуєш у Obsidian — фізично змінюються файли
             │ у ~/dev/portfolio-site/vault/...
             │
             │ нічого не публікується автоматично — ти сам
             │ вирішуєш, коли робити commit + push
             ▼
┌──────────────────────────────────────────────────────────────┐
│  ~/dev/portfolio-site/                                       │
│  ├── vault/                ← Obsidian vault, у git           │
│  │   └── <project>/...     ← один проект = одна папка        │
│  └── astro.config.mjs      ← starlight-obsidian читає vault/ │
└────────────┬─────────────────────────────────────────────────┘
             │ git push origin master
             ▼
┌──────────────────────────────────────────────────────────────┐
│  GitHub: build.yml CI — astro build (npm ci + build)         │
│  Cloudflare Pages — auto deploy з master                      │
└────────────┬─────────────────────────────────────────────────┘
             ▼
       https://docs.ragdoll-labs.com/  (live ~1 хв після push)

Ключове:

Жодних cross-repo sync workflows. Vault живе всередині portfolio-site репо.
starlight-obsidian плагін на час білда читає vault/, конвертує Obsidian-flavor markdown → Starlight pages.
Тема: starlight-theme-galaxy (підключена як Starlight плагін у astro.config.mjs).
Локалі: EN canonical, UA fallback на EN автоматично. Ручні UA-переклади можна додавати у src/content/docs/uk/... (опційно).

Що-куди мапиться

Vault path	Site URL
`vault/<project>/index.md`	`/en/projects/<project>/`
`vault/<project>/adr/0004-foo.md`	`/en/projects/<project>/adr/0004-foo/`
`vault/<project>/design/architecture.md`	`/en/projects/<project>/design/architecture/`

Префікс en/projects задається в astro.config.mjs через output: 'en/projects'.

Сценарій 1 — Звичайне редагування

Відкрий Obsidian → vault ~/Obsidian/portfolio-site (це symlink на репо).
Редагуй що завгодно. SA-skills (sa-analyst, plantuml-master, bpmn-analyst) працюють у цьому vault так само як у Sliptonite.

Коли хочеш опублікувати:

cd ~/dev/portfolio-site
git status
git add vault/
git commit -m "docs: <короткий опис>"
git push origin master

Cloudflare ~30-60 сек робить deploy. Перевір на https://docs.ragdoll-labs.com/.

Якщо НЕ хочеш push’ити — просто не комить. Edit стає на сайт лише після push’у. Це навмисне: гейтом є твій git push, а не factual save.

Сценарій 2 — Сховати окрему сторінку від публікації

Додай у frontmatter ноти:

---
title: My note
publish: false
---

starlight-obsidian ігнорує файли з publish: false. За замовчуванням (без поля) — публікується.

Корисно для:

Чорнових нотаток у vault, які ще не готові
Внутрішніх template/scratch файлів

Альтернатива — глобальний glob через ignore: ['drafts/**', '**/*.private.md'] у astro.config.mjs (зараз не налаштовано, додай якщо знадобиться).

Сценарій 2a — Wiki-style “лінк наперед” на ще-неіснуючу сторінку

Природний Obsidian workflow: пишеш ноту і ставиш [[future-decision]] ще до того як створив файл future-decision.md. На сайті:

Якщо ціль існує і опублікована — звичайний клікабельний лінк.
Якщо ціль відсутня або має publish: false — рендериться як неклікабельний <span class="broken-link"> (підкреслення пунктиром, opacity 0.7, hover показує “Page not found in vault”). Display text зберігається: [[0099-foo|the future ADR]] → span з текстом “the future ADR”.
Білд НЕ падає на broken links — деплой завжди йде.

Технічно це робить post-build скрипт scripts/disable-broken-links.mjs. Плагін генерує звичайний <a> для wikilink (навіть якщо ціль не існує), а скрипт після astro build сканує dist/, будує set валідних URL, і всі <a href> що не резолвляться → конвертує у <span>. Той самий скрипт фіксить bug у starlight-obsidian де alias-redirect pages (aliases: у frontmatter) генеруються з помилковим /index суфіксом у URL.

CSS для .broken-link живе у src/styles/broken-link.css.

Коли ти потім створиш future-decision.md — наступний білд побачить файл, плагін згенерує сторінку, скрипт побачить що URL валідний → лінк автоматично стане клікабельним. Жодних правок старих нот не треба.

Сценарій 3 — Додати новий проект

cd ~/dev/portfolio-site
mkdir -p vault/agile-planner
# створи vault/agile-planner/index.md з frontmatter (title) + опис
git add vault/agile-planner
git commit -m "docs: add agile-planner"
git push origin master

Все. Жодних додаткових кроків:

Sidebar генерується автоматично плагіном (obsidianSidebarGroup в astro.config.mjs).
URL з’явиться як /en/projects/agile-planner/....
Cloudflare передеплоїть.

Сценарій 4 — Локальний preview перед push’ом

cd ~/dev/portfolio-site
npm run dev               # http://localhost:4321
# або
npm run build && npm run preview

Плагін регенерує сторінки з vault при старті dev-server’а та при кожному save.

Frontmatter, який підтримує плагін

copyFrontmatter: 'all' у конфізі → всі custom поля (type, id, status, deciders, related, …) пробиваються у згенеровані сторінки. Спеціально оброблені:

Поле	Поведінка
`title`	Заголовок сторінки. Якщо немає — береться з H1 у тілі або з імені файлу.
`aliases`	Створюються redirect’и з alias-URL на канонічну.
`publish`	`false` → файл скіпається. Default — публікується.
`tags`	Підтримуються (Obsidian inline tags теж).
`description`	Meta-опис.

Що НЕ працює (відомі обмеження `starlight-obsidian`)

Embeds типу “List” та “Search results” (Obsidian-only) — нічого не вийде.
Canvas, Graph, Backlinks panels — Obsidian-only фічі, не сайт.
Wikilink на файл з publish: false або на неіснуючий файл — рендериться як неклікабельний <span class="broken-link"> (це фіча, див. Сценарій 2a).
aliases: у frontmatter — створюють redirect-сторінки, але плагін генерує URL з помилковим /index суфіксом. Виправляється post-build скриптом (scripts/disable-broken-links.mjs).

Перевірені та робочі: callouts, math, mermaid, footnotes, image embeds (з розмірами), youtube/twitter embeds, internal wikilinks, custom display text ([[file|text]]), heading/block links.

Troubleshooting

CI fail — “data does not match collection schema”

Frontmatter сторінки не пройшов Starlight schema. Зазвичай — відсутній title. Або:

Додай title: ... у frontmatter
Або додай # H1 у тілі (плагін витягне)

CI fail — “Cannot find module”

Локально:

cd ~/dev/portfolio-site
rm -rf node_modules package-lock.json
npm install
npm run build

Якщо локально працює — закомітити package-lock.json і пушнути.

Cloudflare не оновлюється

Cache: Cmd+Shift+R, зачекай хвилину.
dashboard.cloudflare.com → Workers & Pages → portfolio-site → Deployments. Має бути запис на твій latest commit.
Build error в CF: відкрий деплой → build log. Зазвичай той самий fail що в GH build.yml.

Obsidian не бачить файли в vault

Symlink ~/Obsidian/portfolio-site міг розв’язатись. Перевір:

ls -la ~/Obsidian/portfolio-site
# має показати: ~/Obsidian/portfolio-site -> /Users/zipsybok/dev/portfolio-site/vault

Якщо ні:

rm ~/Obsidian/portfolio-site  # тільки якщо це symlink, НЕ якщо папка з файлами!
ln -s ~/dev/portfolio-site/vault ~/Obsidian/portfolio-site

Що НЕ треба робити

❌ Не редагуй src/content/docs/en/projects/... напряму. Це більше не існує — плагін генерує тимчасові файли під час білду. Canonical — vault/<project>/....
❌ Не клади у vault personal/private нотатки які не призначені для публікації, БЕЗ publish: false. За замовчуванням все публікується.
❌ Не комітить vault/.obsidian/workspace*.json — гітіґнор має це покривати, але перевір якщо щось дивне.
❌ Не повертай старий sync-flow з окремих project-репо. Стара схема (symlinks Sliptonite/Efforts/Active/<project> → ~/dev/<project>/docs/) усунута. Якщо хочеш писати docs у project-репо — копіюй у vault коли готовий публікувати, або підключи окремий subdirectory у vault як другий source через ignore.

Корисні референси

Live site: https://docs.ragdoll-labs.com/
Repo: https://github.com/Panda-Sensei-1584/portfolio-site
Local vault path: ~/dev/portfolio-site/vault/ (symlink: ~/Obsidian/portfolio-site/)
Astro Starlight: https://starlight.astro.build/
starlight-obsidian: https://starlight-obsidian.vercel.app/
starlight-theme-galaxy: https://frostybee.github.io/starlight-theme-galaxy/
Cloudflare dashboard: dash.cloudflare.com → Workers & Pages → portfolio-site