Skip to content

Migrate docs from GitBook to Astro Starlight - #138

Open
fuksman wants to merge 3 commits into
mainfrom
migration
Open

Migrate docs from GitBook to Astro Starlight#138
fuksman wants to merge 3 commits into
mainfrom
migration

Conversation

@fuksman

@fuksman fuksman commented Aug 12, 2026

Copy link
Copy Markdown
Member

Summary

Replaces the GitBook export with a self-hosted static site built on Astro Starlight, following the same approach as the any-sync docs migration.

Content

  • All GitBook pages converted to Starlight Markdown: hints → asides, {% embed %} → responsive video iframes (YouTube/Vimeo/Loom/Drive) or links, figures → images, stepper/tabs/content-ref unwrapped,   artifacts removed, internal .md links rewritten to site URLs.
  • URL structure preserved from GitBook, so existing links keep working.
  • Navigation generated from SUMMARY.md into sidebar.mjs (now the editable source of truth), including Spanish label translations.
  • Only the 223 referenced assets (138 MB of 582 MB) carried over to public/assets/ with cleaned-up filenames.

i18n

  • English (root) + Español (75 pages, fully mirrors English) + Français (homepage) via Starlight locales; untranslated pages automatically fall back to English.
  • The stale ru-RU / zh-CN / hu_HU trees translated an old docs structure that no longer exists in English (only 1–4 pages each matched current paths) and were dropped; they remain recoverable from git history.

Theme

  • GitBook-style Starlight theme with light/dark toggle: uniform background, blue accent, prominent search, centered max-width layout, compact TOC.
  • Self-hosted Inter + JetBrains Mono (no external CDN), Anytype app icon as logo/favicon.

Verification

  • npm run build: 217 pages, zero leftover GitBook syntax, zero missing assets, zero broken internal links (checked across the whole dist/).
  • Spot-checked rendered pages locally: translated titles, asides, comparison tables, <details> FAQs, video embeds, and locale fallback.

Local development

npm install
npm run dev

🤖 Generated with Claude Code

fuksman and others added 3 commits August 12, 2026 12:20
Replace the GitBook export with a static Astro + Starlight site
(same approach as the any-sync docs migration):

- Convert all pages to Starlight Markdown: hints to asides, embeds to
  responsive video iframes or links, figures to images, stepper/tabs/
  content-ref unwrapped, internal .md links rewritten to site URLs.
- Keep the GitBook URL structure; generate sidebar.mjs from SUMMARY.md
  with Spanish label translations.
- i18n: English (root) + Español + Français via Starlight locales with
  automatic English fallback. Drop the stale ru-RU/zh-CN/hu_HU trees,
  which translated a docs structure that no longer exists (recoverable
  from git history).
- Copy only the 223 referenced assets (138 MB of 582 MB) to
  public/assets with cleaned-up names; drop the rest of .gitbook/.
- GitBook-style theme with light/dark toggle, Inter + JetBrains Mono
  (self-hosted), Anytype app icon as logo/favicon, centered max-width
  layout, compact TOC.
- Update README and CONTRIBUTING for the new stack.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
✅ Deployment successful!
View logs
docs 2b27f4e Aug 12 2026, 10:30 AM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant