Cloud Migration Trail Authoring Guide

Das Ausarbeiten umfassender Migrationspfade verbindet verstreute Einzel-Assets zu einer einheitlichen Workspace-Journey. Die zentrale Layout-Engine interpretiert strukturierte Parameter und baut daraus interaktive Timeline-Tracks für Entwickler.

---

Ordnerstruktur und Lade-Anforderungen

Damit der Loader eine Journey automatisch erkennt und registriert, müssen die Dokumente präzise Workspace-Dateipfade einhalten.

• Ziel-Speicherverzeichnis: Speichere die Konfigurationsdatei im folgenden Verzeichnis des Workspace-Repos:

apps/docs/src/content/docs/[framework-slug]/trails/[contributor-slug]/[trail-slug].mdx

• Erforderliche Konfigurations-Property: Das Frontmatter muss den Basis-Schlüssel scfTrail enthalten. Fehlt er, überspringt der Indexierungs-Loader das Dokument, damit Work-in-Progress-Inhalte verborgen bleiben.
• Optionale Tags: Bis zu 10 Tags unter scfTrail.tags (je max. 20 Zeichen) machen den Trail auffindbar. Die Card zeigt die ersten paar plus einen +N-Chip; alle Tags sind im Trail-Explorer durchsuchbar.

---

Step-Phasen-Styles (style-Enum)

Jeder Timeline-Step nimmt einen optionalen style-Schlüssel, der den Meilenstein mit seiner Journey-Phase markiert. Dies sind die vom Content-Schema validierten Werte:

Seitlich wischen, um die ganze Tabelle zu sehen

Style-Schlüssel	Meilenstein-Phase
compass	PLAN — strategisches Alignment, Assessments und Migration-Discovery.
hut	BASE — Baseline-Umgebung und Voraussetzungen.
stairs	STEP — Engineering-Kernanforderungen und Plattform-Reife.
t-bar	LIFT (niedrig) — inkrementelle Aktivierung von Capabilities.
chairlift	LIFT (mittel) — Skalierung über Teams hinweg.
gondola	AUTO — Continuous Delivery und automatisierte Workflow-Pipelines.
shield	SAFE — Governance-Validierung, Security-Baselines und C5-Compliance.
crevasse	WARN — Risiken, Fallstricke und Remediation-Checkpoints.
chart	OPS — Observability, Kosten und operative Steuerung.
rocket	LIVE — Produktiv-Launches und Go-Live-Meilensteine.
summit	GOAL — Meilenstein-Abschluss, Übergabe und Monitoring.

Der style-Wert ist optional. Steps ohne ihn rendern weiterhin korrekt.

---

Step-Konfigurationstypen

Timeline-Items enthalten entweder eigene Beschreibungen oder dynamische Links zu Framework-Dokumenten.

1. Deskriptive Kontext-Items

Ideal für Steps, die ein übergeordnetes Konzept oder eine Phase beschreiben, für die noch kein Code-Repository existiert. Der Autor liefert title und ein description-Feld manuell.

2. Verknüpfte Komponenten-Items

Verweist über die Astro-ID (assetId) direkt auf ein dynamisches Codebeispiel oder Pattern. Der Parser ruft die Asset-Informationen ab, löst die Creator-Daten auf und rendert eine interaktive SCFAssetCard direkt auf dem Meilenstein-Track. Ein optionaler #section-anchor an der assetId bettet nur diesen Abschnitt des Assets statt des ganzen Dokuments ein, genau wie bei den Seiten-Referenzen unten (z. B. .../assetcontainer/stackit/howto-contributors#directory-structure--asset-placement).

3. Seiten-Referenz-Items

Verknüpft über pageId eine reguläre Framework-Seite (kein Asset). Der Step rendert eine interaktive SCFPageCard und bettet den Seiteninhalt direkt in die Timeline ein. Ein optionaler #section-anchor rendert nur diesen Abschnitt der Seite statt des ganzen Dokuments, z. B. migration/migrate/#core-modules-in-this-phase.

---

Steps als Unterpunkte verschachteln (role)

Lange Trails arbeiten oft mehrere Abschnitte derselben Quelle ab, und wenn sich für jeden davon der volle Step-Kopf (Stage-Marker + Asset-Card + Contributor-Card) wiederholt, wird die Timeline unübersichtlich. Gib so einem Step role: sub, und er nistet als kompakte, mit Buchstaben (a, b, …) markierte Zeile unter dem nächsten vorherigen Hauptschritt — nur Titel und eine Zeile Kontext, kein Stage-Marker, keine Cards. Steps sind standardmäßig role: main, Bestandstrails bleiben also unverändert.

• Gruppierung — Sub-Steps hängen sich an den Hauptschritt darüber. Ein sub ohne vorherigen Hauptschritt wird als Hauptschritt behandelt.
• Fremdquellen — zeigt ein Sub-Step auf eine andere assetId / pageId als sein Hauptschritt, erscheint ein Quell-Chip in der Zeile und ein schlanker Source-Banner (Logo · Titel · Contributor · Kategorie · Öffnen-Link) über seinem Inhalt, damit der Leser die Herkunft kennt. Gleiche Quelle wie der Hauptschritt = nichts Zusätzliches.
• Alle aufklappen — ein einzelner Button über der Timeline öffnet oder schließt alle Sub-Steps auf einmal.
• Präsentations-Bezug — die role eines Steps ist auch die Standard-Agenda-Rolle, wenn der Trail präsentiert wird (siehe Präsentations-Guide), sodass sub-Steps ohne Zusatzaufwand als eingerückte Unterpunkte durchkommen.

- style: "stairs"
  title: "Landing Zone bereitstellen"
  assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"
  trailContext: "Der Accelerator stellt die Baseline bereit. Die nächsten Zeilen gehen seine Schichten durch."
- role: "sub"
  title: "Module im Einzelnen"
  assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu#module-by-module-breakdown"
  trailContext: "Governance, Konnektivität und DevOps: was jedes Modul bereitstellt."
- role: "sub"
  title: "Account-Governance"
  pageId: "migration/design-and-mobilize/design/account-governance"
  trailContext: "Eine andere Quelle, daher zeigt diese Zeile einen Source-Banner."

---

Einem Step ein eigenes Bild geben

Ein Step kann ein Schaubild tragen. In der Timeline erscheint es unter dem Step; in der Präsentation wird es zur zweiten Spalte der Folie oder zu einem vollbreiten Cover. Zwei Felder steuern das Layout in beiden Fällen:

• imagePosition: Weglassen zentriert das Bild — ein Cover, das die Folie unter dem Titel spannt, der Step-Text folgt darunter (full sagt dasselbe explizit). right oder left stellt das Bild stattdessen neben den Text.
• imageWidth: die Breite der Bildspalte in Prozent für left / right (20–70, Standard 45). Bei zentrierten Covern ignoriert.

Beide Felder sind optional, Bestandstrails funktionieren also unverändert weiter.

Die andere Spalte ist der Inhalt, den der Step ohnehin zeigt — du wählst ihn mit den bekannten Feldern: ein trailContext-Absatz, ein Asset-Abschnitt via assetId mit #section-anchor oder ein Seiten-Abschnitt via pageId mit #section-anchor. “Bild rechts, Asset-Abschnitt links” sind also einfach beide Felder an einem Step:

- style: "gondola"
  title: "Migrate-Phase durchführen"
  pageId: "migration/migrate/#core-modules-in-this-phase"
  imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg"
  imageAlt: "Security-Themen, die die Migrate-Phase begleiten"
  imagePosition: right
  imageWidth: 40

Das Bild selbst wird mit imageSrc benannt, einem Pfad relativ zum Content-Root, sodass du die Datei neben deinem Trail ablegen kannst:

- style: "shield"
  title: "Security und Compliance früh verankern"
  trailContext: "Die Themenkarte unten zeigt, was vor dem ersten Workload stehen muss."
  imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg"
  imageAlt: "Security- und Compliance-Themenkarte"
  imagePosition: full

imageAlt ist zugleich Alt-Text und Bildunterschrift. Erlaubt sind nur Bilder auf dieser Site — ein Pfad mit führendem / funktioniert auch, externe http(s)-Adressen werden bewusst ignoriert. Animierte SVGs funktionieren: Die in der Datei eingebackene Animation läuft in der Timeline und auf der Folie.

---

Inhalt in Spalten platzieren (left / right / center)

Die Bild-Felder oben sind die Abkürzung für „ein Inhalt plus ein Bild”. Für volle Kontrolle über beide Seiten kann ein Step beliebige Inhaltstypen in benannte Slots legen — nicht nur Bilder. Jeder von left, right und center hält genau eine Sache:

• text: "…" — freier Prosatext
• assetId: "…" — eine Asset-Card (ein Zeiger). Mit einem #section-anchor wird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mit cards: true bleibt sie sichtbar).
• pageId: "…" — eine Page-Card (ein Zeiger). Mit einem #section-anchor wird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mit cards: true bleibt sie sichtbar).
• trailId: "…" — eine Trail-Card (ein Zeiger auf einen anderen Trail).
• imageSrc: "…" (+ imageAlt) — ein Schaubild (Klick zum Zoomen)

Card = Zeiger, #anchor = Inhalt. Das ist die Kernregel für Spalten: eine nackte assetId / pageId / trailId rendert nur die Card — einen kompakten Zeiger, der sagt „hier ist die Sache”. Soll der Leser tatsächlich etwas von diesem Inhalt in der Spalte sehen, hänge einen #section-anchor an eine assetId oder pageId, und genau dieser eine Abschnitt wird eingebettet — die Card ist dabei standardmäßig ausgeblendet, sodass die Spalte nur den Abschnitt zeigt (an ihrer Stelle steht eine kompakte Herkunfts-Breadcrumb Framework › Titel, damit der Leser trotzdem sieht, woher er stammt). Trail-Cards sind immer Zeiger (ein Trail hat keine Abschnitte zum Einbetten). Ein ganzer Asset- oder Seiten-Body ist für eine Spalte zu hoch — willst du den vollständigen Inhalt im Deck, referenziere ihn als flachen Step (assetId / pageId auf Step-Ebene, nicht in einer Spalte).

Card zeigen mit cards: true. Weil ein Step, der mehrere Abschnitte derselben Quelle stapelt, sonst vor jedem einzelnen dieselbe Card stünde, blendet eine Abschnitts-Spalte die Card standardmäßig aus. Willst du den Zeiger doch über dem Abschnitt sehen, setze cards: true auf die Spalte, dann erscheint er über dem eingebetteten Inhalt. Das Flag greift nur, wenn die Spalte wirklich einen Abschnitt trägt; ein nackter Zeiger behält seine Card immer und rendert damit nie als leere Spalte.

Mehrere Einträge in einem Slot. left, right und center akzeptieren jeweils auch eine Liste. Die Einträge stapeln in der angegebenen Reihenfolge innerhalb der Spalte, getrennt durch einen dünnen Trenner, und sie dürfen aus verschiedenen Quellen kommen: drei Abschnitte eines Assets links, zwei Seiten rechts.

Wo jeder Slot rendert:

Seitlich wischen, um die ganze Tabelle zu sehen

Frontmatter	Layout
left: + right:	zwei Spalten nebeneinander (Split)
nur left:	dieser Inhalt in der linken Hälfte, links
nur right:	dieser Inhalt in der rechten Hälfte, rechts
center:	dieser Inhalt zentriert als Cover
nichts davon	der Step rendert wie zuvor (rückwärtskompatibel)

Unter ~900px stapeln die Spalten. Für einen Split setzt splitRatio die Breite der linken Spalte in Prozent (10–90, Standard 50). Timeline und Präsentationsfolie nutzen dasselbe Layout, was du hier komponierst, zeigt also auch das Deck.

# Split: ein Seiten-Abschnitt links, ein Asset rechts, 55/45
- style: "stairs"
  title: "Entscheidung, dann das umsetzende Werkzeug"
  splitRatio: 55
  left:
    pageId: "migration/design-and-mobilize/design/overview/#decision-criteria-by-r-strategy"
  right:
    assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"

# Text links, ein Schaubild rechts
- style: "shield"
  title: "Security früh verankern"
  left:
    text: "Die Themenkarte vor dem ersten Workload abbilden, nicht erst im Audit."
  right:
    imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg"
    imageAlt: "Security- und Compliance-Themenkarte"

# Center: ein einzelnes Cover-Schaubild (oder zentrierter Text)
- style: "chart"
  title: "Das ganze Terrain"
  center:
    imageSrc: "advisory/trails/stackit/getting_started/map-overview.svg"
    imageAlt: "Framework-Übersichtskarte"

# Mehrere Abschnitte in einer Spalte: Cards standardmäßig aus, je unter der Herkunfts-Breadcrumb
- style: "stairs"
  title: "Drei Schritte desselben Runbooks"
  splitRatio: 60
  left:
    - assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu/#overview"
    - assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu/#deployment-flavours-and-what-they-enable"
  right:
    text: "Jeder Abschnitt behält seine Herkunfts-Breadcrumb, sodass der Leser die drei auseinanderhält, ohne drei identische Cards. Mit cards: true zeigst du die Zeiger-Card einer Spalte doch an."

---

Alternative Steps: alternative Spuren an einem Step (alternatives)

Manchmal hat eine Etappe mehrere gleichwertige Wege: die VMs mit dem Standard-Guide migrieren, mit einem Live-Migration-Tool oder mit einem Replikations-Tool. Ohne Alternativen müsstest du drei Steps für eine Entscheidung bauen oder die Alternativen weglassen. Mit Alternativen bleibt der Step ein Wegpunkt (ein Titel, ein Stage-Marker, ein Agenda-Eintrag) und trägt mehrere Spuren, zwischen denen die Leser umschalten.

• Das assetId / pageId des Steps (oder ohne beides sein trailContext-Text) ist die Standard-Spur. Für bestehende Trails ändert sich nichts: alternatives ist rein additiv.
• Jede Alternative braucht eine stabile id (Deep-Links und Präsentations-Views hängen daran) und trägt genau eine der drei Inhaltsarten eines flachen Steps: ein assetId, ein pageId (beide mit optionalem #section-anchor) oder ohne beides reinen Text aus label + trailContext.
• label ist der Name in der Auswahl; bei Asset- und Seiten-Spuren fällt er auf den referenzierten Titel zurück.
• Ein eigener trailContext an einer Alternative ersetzt für diese Spur den des Steps. Er ist zugleich die Sprechernotiz dieser Spur in der Präsentation.
• Grenzen: bis zu 4 Alternativen je Step und nur an flachen Haupt-Steps. Sub-Steps (role: sub) und Spalten-Steps (left / right / center) unterstützen keine Alternativen; der Validator sagt es dir, wenn du es versuchst.

Auf der Seite rendert der Step seine aktive Spur genau wie ein normaler Step, mit den Asset- und Contributor-Karten der Spur. Eine leise Zeile unter den Karten („2 alternatives for this step”) öffnet die Auswahl; ein Klick tauscht Karten und Inhalt an Ort und Stelle. Die Wahl landet als ?alt=<step-id>:<alternative-id> in der URL (kommagetrennt über mehrere Steps), ein Link kann also eine bestimmte Route teilen — gib Alternative-Steps dafür eine eigene Step-id. „Copy for AI” exportiert immer die gerade gezeigte Spur und nennt die Alternativen.

In der Präsentation bietet der Launch-Screen je Alternative-Step eine Spurauswahl (Voreinstellung ist, was die Seite gerade aktiv hat), und eine vorbereitete Ansicht kann per alternative: an ihrer Step-Referenz eine Spur festlegen — siehe den Präsentations-Guide weiter unten.

- style: "stairs"
  id: "migrate-vms"
  title: "Migrate the Virtual Machines"
  trailContext: "Move the compute layer in waves. Pick the alternative that matches your downtime budget."
  assetId: "migration/assetcontainer/stackit/migration-asset"
  alternatives:
    - id: "hystax"
      label: "Live migration with Hystax Acura"
      assetId: "migration/assetcontainer/hystax/hystax-acura-live-migration"
      trailContext: "For near-zero downtime windows."
    - id: "coriolis"
      assetId: "migration/assetcontainer/cloudbase/cloudbase-coriolis"
    - id: "manual"
      label: "Manual wave migration"
      trailContext: "Plan and execute the waves by hand with the runbooks."

---

Produktives Frontmatter-Blueprint

Kopiere dieses Metadaten-Layout als Basis-Vorlage für eine neue Tracking-Timeline. Ergänze optional eine maintainers-Liste unter scfTrail, um die Maintainer als Ansprechpartner zu würdigen (über der Git-Historie angezeigt), dasselbe Feld nutzen auch Assets:

Mit einem STACKIT-Git-Account trägst du dich nur mit dem Usernamen ein. Voller Name, Biography, Website und Adresse kommen aus deinem Git-Profil und werden täglich von der Pipeline gespiegelt. Die drei Schalter unten sind standardmäßig aus und folgen einer Regel: true nimmt den Wert aus dem Profil, ein String setzt ihn fest.

scfTrail:
  maintainers:
    - user: "jane.doe"

Seitlich wischen, um die ganze Tabelle zu sehen

Feld	Zweck
user	STACKIT-Git-Username. Schlüssel für das gespiegelte Profil und Rückfallanzeige, solange noch nichts gespiegelt wurde.
role	Setzt den Rollentext wörtlich. Für Personen ohne Konto: bei einem user erscheint stattdessen die Biography aus dem eigenen Profil, und nur mit deren Freigabe.
website	Setzt eine URL wörtlich, gleiche Regel wie role.
email	Setzt eine Adresse wörtlich, gleiche Regel wie role. Sie erscheint als eigene Mail-Aktion und steht damit neben einem Profil-Link, statt mit ihm zu konkurrieren.
name	Überschreibt den gespiegelten Namen und würdigt Personen ohne Git-Account. Damit wird der Eintrag zur Person: Initialen-Avatar, Rollenzeile Rolle · Organisation.
contributor	Slug eines /contributors/<slug>-Profils, für Personen ohne Konto. Allein gesetzt würdigt es die Organisation mit Profiltitel, Logo-Initialen und offiziellem Partner-Kennzeichen. Neben einem user wird es ignoriert, dessen Organisation kommt aus der Zuordnungsdatei.
link	Ein Profil- oder Homepage-Link, typischerweise LinkedIn. Er hat Vorrang vor der gespiegelten Website und vor dem Contributor-Profil.

Jedes Feld ist einzeln optional und beliebig kombinierbar; ein Eintrag braucht nur mindestens user, name, contributor oder email, und pro Trail sind bis zu 6 Einträge erlaubt. Felder, die das Schema nicht kennt, werden ohne Fehler verworfen: ein Tippfehler lässt den Build grün und zeigt nichts an. Maintainer sind eine Würdigung, keine Berechtigung, die Liste schränkt also nicht ein, wer den Trail bearbeiten darf. Der Asset-Integrations-Leitfaden zeigt zusätzlich, wie externe Partner ohne Account gewürdigt werden.

---
title: "Standard Kubernetes Onboarding Track"
description: "A comprehensive guided journey trail directing engineering workloads from legacy virtualization targets into sovereign managed STACKIT clusters."
scfTrail:
  # Optional: Maintainer als Ansprechpartner würdigen (über der Git-Historie angezeigt).
  maintainers:
    - name: "Jane Doe"
      role: "Trail Owner"
  steps:
    - style: "compass"
      title: "Initial Assessment Phase"
      trailContext: "Analyze workload traits and infrastructure requirements before initializing resources."

    - style: "gondola"
      assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"
      trailContext: "Deploy the landing zone automated profile using standardized infrastructure code scripts."

    - style: "stairs"
      title: "Execute the Migration Modules"
      trailContext: "Work through the core migration modules; the optional #anchor renders only that page section."
      pageId: "migration/migrate/#core-modules-in-this-phase"

    - style: "summit"
      title: "Final Cluster Validation"
      description: "Review compliance policies and confirm that all configuration checks pass security rules."
---

---

Referenz-Links in unterstützenden Seiten

Die Trail-Datei selbst ist frontmatter-only, deshalb greift die Link-Regel dort nie: Text in trailContext und in Spalten-text wird als reiner Text gerendert, Links eingeschlossen. Sie gilt aber für die Asset- und Content-Seiten, auf die deine Steps zeigen: dort muss jeder Verweis, der auf einer eigenen Zeile steht, eine <LinkCard> oder ein <LinkChip> sein — beide automatisch importiert, beide leiten ihre Art (Portal, Marketplace, Dokumentation, Code, Drittanbieter) allein aus der URL ab. Die PR-Pipeline blockiert nackte alleinstehende Links in geänderten Dateien und prüft, dass interne Karten- und Chip-Ziele existieren. Die vollständige Regel steht im Asset Integration Guide.

---

Einen Trail präsentieren

Jeder Trail lässt sich über den Präsentations-Button in seiner Detailansicht als Foliendeck öffnen — kein zusätzliches Frontmatter nötig. Als Autor kannst du zusätzlich vorbereitete Ansichten (kuratierte Folien-Auswahlen) definieren, das Start-Verhalten vorpresetten und das Bild eines Steps zu einer Split-Folie machen. All das lebt in einem presentations-Block unter scfTrail und ist in einem eigenen Guide dokumentiert: dem Präsentations-Guide.

---

SCF Studio

Nutze das SCF Studio, um einen Trail zu bauen, ohne YAML von Hand zu schreiben. Starte die Docs (hike) und öffne /studio in deinem Dev-Container, oder nutze es auf der Dev-Seite. Es baut die Steps, löst jedes Asset und jede Seite auf, auf die du zeigst, und es kann einen bestehenden Trail laden und nur das ändern, was du bearbeitest.

---

Live Component Playground (lokaler Dev-Server)

Starte die Docs lokal (VS-Code-Task 🥾 Hike — Start Dev Docs oder das hike-Kommando im Container-Terminal, ausgeliefert auf http://localhost:4321) und öffne die interaktiven Playgrounds, um die Trail-Komponenten live gerendert zu sehen:

• Trail Loader — das automatisch erkannte, höhengleiche Trail-Grid genau wie via <ScfTrailLoader /> eingebettet, inklusive Inline-Detailansicht: http://localhost:4321/demo/components/demo-scf-trail-loader
• Trail (einzelne Timeline) — die vollständige interaktive Meilenstein-Timeline mit Accordion-Asset-Cards, die style, assetId, title und trailContext pro Step demonstriert: http://localhost:4321/demo/components/demo-scf-trail

---

Zentrale Übersicht

Zur Cloud-Framework-Trails-Übersicht

Zurück zum zentralen Verzeichnis mit allen live gerenderten, interaktiven Migrations-Journeys und Entwickler-Tracks.