Knowledge Base Migration: ReadMe.io to Docusaurus

Context

Vianova's knowledge base (~280 markdown docs + 6 API recipes) is currently hosted on ReadMe.io at help.vianova.io. The system needs to be replaced due to: cost, poor editing experience for non-technical users, lack of real-time collaboration, no self-hosting/data ownership, limited customization, and no multilingual support.

Critical requirement: Translation into all EU languages (~24), with potential Arabic (RTL) and Japanese (CJK) support. English is the source of truth. Crowdin is already in use.

Architecture

• Docusaurus 3 — static site generator with first-class i18n support
• Crowdin — translation management (existing tooling)
• Git repo — single source of truth (English markdown)
• AWS S3 + CloudFront — hosting (existing Vianova infra)
• Algolia DocSearch — search
• GitHub Actions / existing CI — build & deploy pipeline

Content Flow

PM writes/edits markdown (with LLM assistance)
  -> PR to git repo (English)
    -> Crowdin CLI syncs source strings
      -> Translators / MT fill in 24+ locales
        -> Crowdin CLI pulls translated files back
          -> CI builds all locales
            -> aws s3 sync + CloudFront invalidation

What Stays Outside

• API reference stays at api.vianova.dev/docs (linked from navbar)

Information Architecture

/                              -> Landing page (custom hero)
/docs/                         -> Knowledge Center (all guides)
  /getting-started/
  /analyzing-mobility-data/
  /planning-streets/
  /managing-policy/
  /vip/
  /streams/
  /using-the-api/
  /cityscope-support/
  /data-producer/
  /intelligent-platform/
  /data-products/
/recipes/                      -> API recipes (separate docs plugin instance)
/changelog/                    -> Blog-powered changelog
/roadmap/                      -> Custom page

Navbar: Docs | Recipes | API Reference (external) | Changelog | Roadmap | Language switcher

Visual Design

• Purple brand palette: --ifm-color-primary: #6B0070, gradient to #220023
• Vianova logo in navbar
• Match current clean, professional look from help.vianova.io
• Swizzle minimal theme components (navbar, footer, sidebar)
• Admonitions replace ReadMe callout boxes
• Optional dark mode toggle

Content Migration (One-Time)

Docs (~280 files)

1. Strip ReadMe-specific frontmatter (recipe:, deprecated:, hidden:, metadata:)
2. Convert <Image> components to standard markdown images
3. Convert _order.yaml files to sidebars.js + _category_.json position metadata
4. Preserve folder hierarchy as-is (maps directly to Docusaurus sidebar)

Recipes (6 files)

1. Convert <!-- python@X-Y --> line references to Docusaurus code block line highlighting ({X-Y})
2. Convert recipe: frontmatter to standard Docusaurus frontmatter with tags
3. Set up as a separate docs plugin instance at /recipes

API-Referenz

• Delete reference/ directory contents (Hawkeye specs)
• Add external navbar link to api.vianova.dev/docs

Translation Pipeline

Setup

• Configure docusaurus.config.js with all target locales
• Configure Crowdin project with crowdin.yml mapping Docusaurus i18n structure
• RTL support enabled for Arabic locale

Ongoing Workflow

1. Author writes/edits English docs, merges PR
2. CI runs docusaurus write-translations to extract strings
3. Crowdin CLI uploads source files
4. Translation happens in Crowdin (MT + optional human review)
5. Crowdin CLI downloads translated files into i18n/<locale>/
6. CI builds and deploys all locales

Hosting & Deployment

• S3 bucket — stores built static files
• CloudFront distribution — CDN, SSL, custom domain (help.vianova.io)
• CI pipeline — on merge to main: build all locales, aws s3 sync, CloudFront cache invalidation
• Preview deploys — on PR: build and deploy to preview URL for review

Editing Workflow for PMs

• PMs write/edit markdown with LLM assistance (Claude, ChatGPT)
• Changes submitted as PRs via GitHub web UI or git
• Preview deploy on PR for visual review
• Merge triggers production deploy

Success Criteria

• All existing docs and recipes migrated and accessible
• Translation pipeline working end-to-end with Crowdin
• Site live at help.vianova.io on AWS infra
• Search functional via Algolia
• PMs can edit and preview without developer assistance
• Visual design matches Vianova branding