Migrate from Paligo + Webpack to Docusaurus 3

[matenadasdi]

Summary

Replaces the custom Paligo CMS + Webpack pipeline with a Docusaurus 3 site backed by an XML → Markdown/MDX migration. Preserves every existing live URL (444/444), ports all integrations (OneTrust, GTM, Intercom, Google Search Widget), and matches the live site's visual identity and navigation.

What's in the box

Migration pipeline (migration/)

• convert.py — Paligo XML export → Markdown/MDX. Walks the <e:structure> tree, resolves linked components by origin UUID, converts DocBook bodies (sections, admonitions, tables, procedures, code blocks, lists, cross-references). Detects topichead nodes (non-clickable categories) and linktype="import" subtrees (skipped — content is reused via xi:include).
• build_url_map.py — extracts live page titles from out/en/*.html to drive slug assignment.
• apply_slugs_v2.py — section-aware slug matcher; only applies a slug when the matched URL lives in the same top-level section, preventing cross-section misroutes for common titles like "Getting started".

Docusaurus features wired up

• Tabs — XML <para role="tabs"> + <procedure role="tab-content"> patterns become MDX <Tabs> / <TabItem> components.
• Glossary — rendered as an HTML <dl> with anchor IDs. Inline glossterm references become <GlossTerm baseform="..."> components with a hover tooltip that click through to the glossary anchor.
• Reusable content fragments via MDX partials — every xi:include target gets one file at src/partials/<readable-slug>.mdx (e.g. opening-the-workflow-editor.mdx). Section-context references render the partial as a JSX component; list-context references use a placeholder line that the Docusaurus markdown.preprocessor expands inline before MDX parsing — keeps step numbering continuous while preserving a single source of truth.
• Topichead categories — Paligo's non-clickable navigation labels become _category_.json entries with link: null, so they expand children without navigating.
• Sidebar labels driven by the live HTML toc (migration/live_nav_labels.json) so navigation reads identically to the published site — e.g. "Insights for the Build Cache" instead of just "Insights".
• Image references rewritten to /img/_paligo/uuid-<hex>.<ext> using the Paligo HTML export as the canonical image store (665 files), since the XML's src/remap attrs often pointed to legacy filenames.
• Portal landing page (src/pages/index.tsx) rebuilt as a React component with the six product cards, Bitrise brand styling, and search input wired for the Google Search Widget.

Integrations

• OneTrust cookie consent banner (production only) via headTags
• GTM via customFields.gtmId (env var)
• Google Search Widget via customFields.genSearchWidgetConfigId (env var)
• Intercom app id wired via customFields.intercomAppId

Why this approach

• Single source of truth for reusable content. The 688 unique reused chunks live in src/partials/ once. Editing the partial cascades to every consumer on next build — no more hunting through dozens of duplicated copies.
• Build-time list expansion sidesteps the fundamental MDX/Markdown limitation that a <Component /> inside a numbered list renders as a block and breaks step numbering. The on-disk consumer file has 1. <Partial_X />; the build splices in the partial's actual list items before MDX parses.
• Section-aware slug matcher prevents the all-"Getting started"-pages-collide problem that the original simple title-match had.

Reviewer notes

• The legacy stack (paligo.js, webpack.config.js, middleware.js, build.js, src/html/, src/js/, etc.) is left in tree on purpose. Cutover happens in a separate PR after this one is verified end-to-end.
• migration/docs/ is in .gitignore — it's the Python script's intermediate output, copied into docs/ by the bash pipeline.
• static/img/_paligo/ holds the 665 Paligo-exported images. Largest part of the diff in raw line count.
• src/partials/ has 592 generated MDX partial files. Each has a readable filename derived from the resource title (e.g. opening-the-workflow-editor.mdx).
• The Docusaurus markdown.preprocessor in docusaurus.config.ts does several things in one pass: list-context partial expansion, JSX-tag escaping for placeholder text like <Git provider> or <connected-app-id>, and {kebab-case} placeholder escaping. Each step has an inline comment explaining the trigger pattern.

Test plan

• Run npm install && npx docusaurus build — should complete with zero broken-link errors
• Confirm URL coverage: 444 of the live pages resolve
• Spot-check the portal page (/) — six product cards render, search input is present, OneTrust banner shows in production builds
• Spot-check a topichead category in the sidebar (e.g. "Getting started" under Bitrise Platform) — should expand/collapse on click without navigating
• Spot-check a list-context partial (/en/bitrise-ci/workflows-and-pipelines/workflows/creating-a-workflow.html) — 7 steps render in continuous numbering, first 2 from "Opening the Workflow Editor"
• Spot-check a glossary inline term — hovering shows the popover, clicking jumps to the glossary anchor
• Edit src/partials/opening-the-workflow-editor.mdx, rebuild, confirm every consumer reflects the change

🤖 Generated with Claude Code