Skip to content

feat: migrate documentation from Docusaurus to Astro Starlight#65

Draft
niderhoff wants to merge 5 commits intotelekom:mainfrom
niderhoff:astro-migration
Draft

feat: migrate documentation from Docusaurus to Astro Starlight#65
niderhoff wants to merge 5 commits intotelekom:mainfrom
niderhoff:astro-migration

Conversation

@niderhoff
Copy link
Copy Markdown
Collaborator

@niderhoff niderhoff commented Apr 5, 2026

Changes

  • Framework: Replace Docusaurus with Astro + Starlight theme.
  • Components: Create pure Astro components (AvailableModels.astro, PlansPage.astro) replacing React+Scale components. Removes react dependency.
  • Styling: Replace Docusaurus CSS (1,460 lines) with Starlight CSS variables + Telekom magenta branding (#e20074)
  • CI/CD: Update GitHub Actions artifact path from build/ to dist/
  • i18n: Use Starlight's built-in locale system (root = English, /de/ = German) replacing i18next
  • German translations: Add full German translations for all 31 pages in src/content/docs/de/
  • Cleanup: Remove Docusaurus theme overrides, Scale components, versioned docs, babel config

Why

  • Faster builds (2.8s vs ~30s)
  • Simpler dependency tree (3 deps vs 20+)
  • Built-in search, i18n, and dark mode without plugins
  • Server-rendered components instead of client-side React hydration
image

PR #63's content changes are now included in this PR

  • "20+" → "30+" models
  • "EU Hosted" badge → "T-Cloud: Germany Only"
  • Updated description about T-Cloud vs hyperscaler data processing
  • Added "Data Processing: Germany/EU" field to model cards
  • All changes applied to both English and German versions

PR #63 can be closed once our migration PR is merged — its changes are fully incorporated.

@niderhoff niderhoff force-pushed the astro-migration branch 2 times, most recently from 82290da to 923554b Compare April 5, 2026 17:57
- Replace Docusaurus 3.9 with Astro 6 + Starlight 0.38
- Port all 31 documentation pages to Starlight MDX format
- Create German translations for all pages (src/content/docs/de/)
- Build Astro components for AvailableModels and PlansPage (replacing React + Scale components)
- Add flag-icons library for country flags
- Telekom-branded custom CSS with Starlight variables
- Bilingual support (English at /, German at /de/)
- Update CI/CD workflow for Astro (dist/ output)
- Include migration spec (MIGRATION_SPEC.md) for reference

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove orphaned JSX components and useMyI18n.js from old Docusaurus setup
- Fix Plans page content alignment to match pages with right sidebar
- Cap LinkCards and pagination links at normal content width
- Prevent table overflow at narrow viewports near 72rem breakpoint
- Align header search bar with content via data-has-toc attribute
@ashwinnair14
Copy link
Copy Markdown

ashwinnair14 commented Apr 7, 2026

Looks good.

  • I see what we have an older docs on the prod docs website. https://docs.llmhub.t-systems.net/1.0.0/smartchat/smartchat-api-reference.
    Do u know if we can safely ignore this ?

  • Remove the file MIGRATION_SPEC.md if u dont think we need it anymore.

  • There is an issue in the code where in the plan section it does not show globe and it only shows the EU flag everywhere for even global as well.

const isEU = m.cloud === 'T-Cloud';                                                                              
  const dpLocation = isEU                                                                                          
    ? '<span class="fi fi-eu"></span> EU'                                                                          
    : '<span class="fi fi-eu"></span> EU & Worldwide'; 
  • How does this logic particularly work in the Plans and pricing page? For example, for cloud 3.7 Sonnet data processing location is EU and worldwide but the server location is Europe. It feels a bit contradictory maybe by this we want to say that like the data processing can happen anywhere and the server location also can be anywhere or maybe I'm misunderstanding how this works. See image.
  • The issue is in AvailableModels.astro — when the copy button is clicked, it replaces the button's textContent with a checkmark emoji, destroying the SVG icon inside. Notice how some of the models dont have the copy button once u click it.
image image

The rest looks good to me 👍
CC should be able to fix the bugs I mentioned

@niderhoff
Copy link
Copy Markdown
Collaborator Author

niderhoff commented Apr 8, 2026

@ashwinnair14

Regarding

How does this logic particularly work in the Plans and pricing page? For example, for cloud 3.7 Sonnet data processing location is EU and worldwide but the server location is Europe. It feels a bit contradictory maybe by this we want to say that like the data processing can happen anywhere and the server location also can be anywhere or maybe I'm misunderstanding how this works. See image.

We'd have to ask @ManvendraSinghJii for the intent here but reverse-engineering leads me to this:

Data Processing Location — derived purely from the hosting platform:
T-Cloud → "EU"
Azure/GCP → "EU & Worldwide"
(line 349 in PlansPage.astro: const isEU = m.cloud === 'T-Cloud')

Server Location — parsed from the deploymentRegion field in the pricing JSON (e.g., azure-europe → "Europe", otc-germany → "Germany")

So they're describing different things:

  • Server Location = where the server physically sits (Europe, Germany, Sweden, etc.)
  • Data Processing Location = a data sovereignty claim about where your data may be processed

No longer needed now that the Astro migration is complete.
The non-EU "Data Processing Location" column was showing the EU flag
for all rows. Use a globe emoji for "EU & Worldwide" entries instead.
Clicking the copy button replaced innerHTML with an emoji, permanently
losing the SVG. Remove the visual feedback entirely — just copy silently.
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.

2 participants