Skip to content

Migrate documentation from Jekyll to Astro Starlight#897

Draft
jordanrburger wants to merge 22 commits intomainfrom
feature/astro-migration
Draft

Migrate documentation from Jekyll to Astro Starlight#897
jordanrburger wants to merge 22 commits intomainfrom
feature/astro-migration

Conversation

@jordanrburger
Copy link
Copy Markdown
Contributor

@jordanrburger jordanrburger commented Mar 24, 2026

Summary

Migrates the entire Keboola documentation site from Jekyll (Ruby/Docker) to Astro Starlight (Node.js), a modern documentation framework.

  • 264 markdown files and 1,218 images migrated to Starlight format
  • Sidebar auto-generated from existing _data/navigation.yml
  • Redirect pages generated from redirect_from frontmatter for URL compatibility
  • CI workflows updated from Docker/Jekyll to Node.js/Astro
  • Deploys to the same S3 bucket (help.keboola.com) with the same caching strategy
  • Client-side navigation with prefetch for fast, flicker-free page loads
  • Custom 404 page

Steps to go live

  1. Review & approve this PR — CI runs npm ci && npm run build on PRs to validate the build
  2. Verify redirects — Spot-check that existing URLs (especially linked from external sources) still work via the redirect_from frontmatter mappings
  3. Confirm AWS secrets — The deploy workflow uses AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (same secrets as today). Verify these are still configured in the repo's GitHub Actions secrets
  4. Merge to main — On merge, the main.yml workflow will:
    • npm ci + npm run build to produce a static dist/ folder
    • aws s3 sync dist s3://help.keboola.com --delete --acl "public-read" to deploy
  5. Verify production — After deploy, check https://help.keboola.com and a few key pages:
    • Homepage loads correctly
    • Sidebar navigation works
    • Search works
    • Old URLs redirect properly
  6. DNS / CDN — No changes needed; the S3 bucket and domain remain the same

What changes in the deploy pipeline

Before (Jekyll) After (Astro)
Runtime Ruby via Docker Node.js 22
Build command jekyll build → _site/ npm run build → dist/
Deploy s3 rm --recursive then s3 cp s3 sync --delete (atomic, safer)
CI on PRs Build only Build only (same)

Test plan

  • CI build passes on this PR
  • Local npm run build produces a clean dist/ output
  • Spot-check 10+ pages for content accuracy vs current live site
  • Verify sidebar navigation matches existing structure
  • Test redirect URLs (pick 5 from redirect_from frontmatter entries)
  • Confirm search functionality works
  • Check mobile responsiveness

🤖 Generated with Claude Code

jordanrburger and others added 22 commits March 18, 2026 16:58
@jordanrburger @claude
Add .worktrees, node_modules, dist to .gitignore
66ee856 
Preparing for Jekyll-to-Astro migration: ignore worktree directory,
Node.js dependencies, and Astro build output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Initialize Astro Starlight project scaffolding
15fc132 
Set up the core Starlight project structure for migrating Keboola docs
from Jekyll: package.json with Astro/Starlight dependencies, astro config
with GTM tracking, Keboola brand CSS overrides, custom Head component for
GTM noscript, content config, and TypeScript config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Add sidebar conversion script and generate Starlight sidebar config
86eecce 
Create scripts/convert-nav.mjs that parses _data/navigation.yml and
produces src/sidebar.mjs with the full Starlight sidebar tree (~200
entries, up to 4 levels deep). Update astro.config.mjs to import and
use the generated sidebar. Add gen:sidebar npm script for easy
regeneration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Add Jekyll-to-Starlight content migration script
2846377 
Transforms all markdown files from Jekyll format to Astro Starlight:
- permalink → slug frontmatter conversion
- Remove layout/showBreadcrumbs, convert sitemap→pagefind
- Convert highlight blocks to fenced code blocks
- Convert tip/warning/beta includes to Starlight admonitions
- Remove TOC markers and Kramdown attribute lists
- Copy images and special assets to correct locations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Update CI workflows: Jekyll/Docker → Astro/Node.js
c3f5f66 
Replace Docker-based Jekyll builds with Node.js 22 + npm ci + npm run build.
Deploy step now uses pip-installed awscli directly and targets dist/ instead of _site/.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Add custom 404 page for Starlight site
2bca593 
Create src/pages/404.astro with branded error page content and copy
keboola-kolecko.png to public/ for the 404 page image.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Migrate 264 markdown files and 1218 images to Starlight format
b3a2e34 
Fix \r\n line ending bug in permalink→slug conversion that caused 34
files to retain their permalink: frontmatter. All Jekyll patterns
(includes, TOC markers, highlight blocks, kramdown attrs, image-popup)
are now fully transformed.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix build errors: upgrade to Astro 6, fix missing images and config i…
1aeca86 
…ssues

- Upgrade from Astro 5/Starlight 0.34 to Astro 6/Starlight 0.38 to resolve
  Zod v3/v4 schema validation conflict that caused build failures
- Add docsLoader() to content config (required by Starlight 0.38)
- Extend docs schema with redirect_from field for Jekyll redirect compatibility
- Copy 4 missing .webp images that were skipped during migration
- Add .webp to IMAGE_EXTS in migration script to prevent future omissions
- Fix CSS @import ordering (must precede other statements)
- Fix sidebar slug: components/data-apps/backend-versions -> data-apps/backend-versions
- Remove src/pages/404.astro that conflicted with Starlight's built-in 404 route
  (404 content is served from src/content/docs/404.md instead)
- Add .astro/ to .gitignore
- Update starlight-image-zoom to v0.14 for Starlight 0.38 compatibility

Build produces 264 pages successfully with Pagefind search index.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Add redirect-from integration to generate redirect pages from frontma…
18de2ab 
…tter

Create a custom Astro integration that reads redirect_from arrays from
content frontmatter and generates static HTML redirect pages (using meta
refresh) during the build. This ensures old URLs continue to work by
redirecting visitors to the correct page. Generates 162 redirect pages
across 152 content files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix post-migration issues: Liquid tags, favicon, deploy, and HTML esc…
0713793 
…aping

- Strip {% raw %}/{% endraw %} and convert {% comment %}/{% endcomment %}
  to HTML comments in migration script (C1: 10 affected files)
- Add favicon: '/favicon.ico' to Starlight config to match public/ asset (C2)
- Replace pip install awscli + rm/cp with aws s3 sync --delete in CI (I2)
- Add escapeHtml() to redirect-from integration for safe URL interpolation (I4)
- Re-run migration to apply Liquid tag fixes to all content files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Polish Starlight migration: sidebar, light mode, images, copy button
474b96b 
- Fix light mode by scoping CSS color overrides to dark/light themes
- Fix sidebar: rename parent page entries to "Overview", collapse all groups
- Fix images: copy content images to public/ for absolute path serving
- Remove duplicate ## Overview headings from 9 content pages
- Add "Copy as Markdown" button to every page for AI agent workflows
- Make GTM conditional on help.keboola.com hostname (no cookie modal on localhost)
- Make logo visible in dark mode with CSS filter

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Update README for Astro Starlight framework
7264685 
Replace Jekyll/Docker instructions with Node.js/Astro setup,
document project structure, content authoring, build process,
sidebar regeneration, and key features.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Enable client-side navigation with Astro ClientRouter
ad72a2a 
Adds <ClientRouter /> to the Head component for SPA-style page
transitions instead of full page reloads on every navigation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Disable view transition animation to prevent flash on navigation
b32b662 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Replace ClientRouter with prefetch for flicker-free navigation
e7a5d4d 
ClientRouter view transitions caused visible flickering. Replaced with
Astro's prefetch (hover strategy) which preloads pages in the background
so they load near-instantly on click without any visual artifacts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix page navigation flickering by self-hosting fonts and enabling Vie…
abdc3bd 
…w Transitions

The render-blocking Google Fonts @import in CSS caused a flash on every page
load. Self-hosting the Lato WOFF2 files eliminates the external request entirely.
Re-enabling Astro ClientRouter (View Transitions) provides SPA-style navigation
so pages swap without full reloads.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix flickering: anti-FOUC background, disable VT animations, use swap…
7d0f366 
… fallback

Three-part fix for page navigation flicker:
1. Inline anti-FOUC styles set correct background color immediately before
   any CSS loads, preventing white flash during theme initialization
2. Disable all View Transition crossfade animations via CSS for instant swap
3. Use "swap" fallback mode for non-VT browsers (instant DOM swap)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Preserve sidebar open/closed state across view transitions
a1ad6ca 
When navigating via View Transitions, the new page's sidebar would reset
group expand states. This script preserves the user's sidebar state while
ensuring the group containing the active page is always open.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Normalize sidebar group label styling to match leaf links
6a67663 
Starlight renders group labels (items with children) as bold by default,
creating visual inconsistency with leaf links at the same nesting level.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix nested sidebar group labels to match leaf link sizing
a521ce0 
Top-level groups keep bold/large styling, but nested sub-groups now use
the same font-size and weight as regular leaf links for consistency.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jordanrburger @claude
Fix empty slug in sidebar config causing Starlight build error
257e21c 
Starlight does not accept slug: "" for sidebar links. Changed to
slug: "index" which correctly references the root docs page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jordanrburger @claude
Add .vercel to .gitignore
cbb1c6f 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jordanrburger
Copy link
Copy Markdown
Contributor Author

jordanrburger commented Mar 24, 2026

This is a draft of the docs migration. It SHOULD NOT be merged until further notice.

@jordanrburger jordanrburger requested review from odinuv and removed request for odinuv March 24, 2026 22:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jordanrburger