Ein Trail verkettet Assets, Seiten und deinen eigenen Text zu einem geführten Pfad. Leser folgen ihm als Timeline. Du kannst ihn auch als Foliendeck präsentieren.
Wo Trail-Dateien liegen
Abschnitt betitelt „Wo Trail-Dateien liegen“Der Loader registriert einen Trail nur, wenn die Datei unter dem Pfad unten liegt und den Schlüssel scfTrail trägt.
- Pfad: Speichere die Trail-Datei unter diesem Pfad im Content-Repository:
docs/[framework-slug]/trails/[contributor-slug]/[trail-slug].mdx- Erforderlicher Schlüssel: Das Frontmatter muss den Schlüssel
scfTrailenthalten. Fehlt er, überspringt der Loader die Datei, damit unfertige Inhalte verborgen bleiben. - Optionale Tags: Bis zu 10 Tags unter
scfTrail.tags(je höchstens 20 Zeichen) machen den Trail auffindbar. Die Card zeigt die ersten paar plus einen+N-Chip; alle Tags sind im Trail-Explorer durchsuchbar.
Step-Styles (style)
Abschnitt betitelt „Step-Styles (style)“Jeder Step nimmt einen optionalen style-Schlüssel, der seine Phase markiert. Das Content-Schema akzeptiert diese Werte:
| 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: Launches und Go-Live-Meilensteine. |
summit | GOAL: Meilenstein-Abschluss, Übergabe und Monitoring. |
Der style-Wert ist optional. Steps ohne ihn rendern weiterhin korrekt.
Step-Typen
Abschnitt betitelt „Step-Typen“Ein Step zeigt entweder Text, den du schreibst, oder eine Karte, die auf eine andere Seite verweist. Zu jedem Typ unten gibt es ein Beispiel.
1. Text-Steps
Abschnitt betitelt „1. Text-Steps“Ein Text-Step passt für eine Idee oder eine Phase, die noch keine eigene Seite hat. Du schreibst title und trailContext. Der trailContext ist der Text, den der Leser am Step sieht. Wie du einen Step schreibst, der auf einer Folie funktioniert, steht unter Steps schreiben, die als Folie funktionieren .
- style: "compass" title: "Assess the workloads before you build" trailContext: "Analyze the workload and its requirements before you create any resources."2. Asset-Steps
Abschnitt betitelt „2. Asset-Steps“Ein Asset-Step verweist über die assetId auf ein Asset. Der Step zeigt die Asset-Karte mit dem Contributor. Ein optionaler #section-anchor an der assetId zeigt nur diesen Abschnitt des Assets statt der ganzen Seite, genau wie bei den Seiten-Referenzen unten (z. B. .../assetcontainer/stackit/howto-contributors#profile-and-logo-paths).
- style: "gondola" title: "The landing zone is the baseline" trailContext: "The accelerator sets up the baseline." assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"3. Seiten-Steps
Abschnitt betitelt „3. Seiten-Steps“Ein Seiten-Step verweist auf eine reguläre Framework-Seite, die kein Asset ist. Du nennst sie mit ihrer pageId. Der Step zeigt die Seitenkarte und den Seiteninhalt direkt in der Timeline. Ein optionaler #section-anchor zeigt nur diesen Abschnitt der Seite statt der ganzen Seite.
- style: "stairs" title: "The migration modules cover the core of this phase" trailContext: "Go through the core modules of this phase." pageId: "migration/migrate/#core-modules-in-this-phase"Steps als Unterpunkte verschachteln (role)
Abschnitt betitelt „Steps als Unterpunkte verschachteln (role)“Lange Trails arbeiten oft mehrere Abschnitte derselben Quelle ab. Wiederholt sich für jeden davon der volle Step-Kopf (Stage-Marker, Asset-Card und Contributor-Card), 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. Die Zeile zeigt nur Titel und eine Zeile Kontext, ohne Stage-Marker und ohne Cards. Steps sind standardmäßig role: main, Bestandstrails bleiben also unverändert.
- Gruppierung: Sub-Steps hängen sich an den Hauptschritt darüber. Ein
subohne vorherigen Hauptschritt wird als Hauptschritt behandelt. - Fremdquellen: Zeigt ein Sub-Step auf eine andere
assetId/pageIdals sein Hauptschritt, erscheint ein Quell-Chip in der Zeile. Ein schlanker Source-Banner (Logo · Titel · Contributor · Kategorie · Öffnen-Link) steht über seinem Inhalt, damit der Leser die Herkunft kennt. Bei gleicher Quelle wie der Hauptschritt erscheint nichts Zusätzliches. - Alle aufklappen: Ein einzelner Button über der Timeline öffnet oder schließt alle Sub-Steps auf einmal.
- Präsentations-Bezug: Die
roleeines Steps ist auch die Standard-Agenda-Rolle, wenn der Trail präsentiert wird (siehe Präsentations-Guide), sodasssub-Steps ohne Zusatzaufwand als eingerückte Unterpunkte durchkommen.
- style: "stairs" title: "Die Landing Zone stellt die Baseline bereit" 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: "Die Module werden einzeln aufgeschlüsselt" 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 hat eine eigene Seite" 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
Abschnitt betitelt „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. Es wird ein Cover, das die Folie unter dem Titel spannt, der Step-Text folgt darunter (fullsagt dasselbe explizit).rightoderleftstellt das Bild stattdessen neben den Text.imageWidth: die Breite der Bildspalte in Prozent fürleft/right(20 bis 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: "Security-Themen begleiten die Migrate-Phase" 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: 40Das 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 kommen vor dem ersten Workload" 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: fullimageAlt 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)
Abschnitt betitelt „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 ProsatextassetId: "…": eine Asset-Card (ein Zeiger). Mit einem#section-anchorwird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mitcards: truebleibt sie sichtbar).pageId: "…": eine Page-Card (ein Zeiger). Mit einem#section-anchorwird stattdessen genau dieser eine Abschnitt eingebettet (die Card ist standardmäßig ausgeblendet; mitcards: truebleibt 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. Sie ist ein kompakter 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. Genau dieser eine Abschnitt wird dann 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:
| 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 bis 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-Themen kommen vor dem ersten Workload" 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 Framework passt auf eine Karte" 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: "Ein Runbook zeigt mehrere Abschnitte nebeneinander" 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 (alternatives)
Abschnitt betitelt „Alternative Steps (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/pageIddes Steps (oder ohne beides seintrailContext-Text) ist die Standard-Spur. Für bestehende Trails ändert sich nichts:alternativesist 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: einassetId, einpageId(beide mit optionalem#section-anchor) oder ohne beides reinen Text auslabel+trailContext. labelist der Name in der Auswahl; bei Asset- und Seiten-Spuren fällt er auf den referenzierten Titel zurück.- Ein eigener
trailContextan 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: "Pick the migration route that fits your downtime budget" 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."Vollständiges Trail-Beispiel
Abschnitt betitelt „Vollständiges Trail-Beispiel“Kopiere dieses Beispiel als Start für einen neuen Trail. Ergänze optional eine maintainers-Liste unter scfTrail, um die Maintainer als Ansprechpartner zu würdigen (über der Git-Historie angezeigt). Assets nutzen dasselbe Feld.
Mit einem STACKIT-Git-Account trägst du dich nur mit dem Usernamen ein. Mehr braucht der Eintrag nicht:
scfTrail: maintainers: - user: "jane.doe"| 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: "Assess the workloads before you build" 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: "The migration modules come next" 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: "Validate the cluster before go-live" trailContext: "Review compliance policies and confirm that all configuration checks pass security rules."---Referenz-Links in unterstützenden Seiten
Abschnitt betitelt „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 sind automatisch importiert und 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
Abschnitt betitelt „Einen Trail präsentieren“Jeder Trail lässt sich über den Präsentations-Button in seiner Detailansicht als Foliendeck öffnen. Zusätzliches Frontmatter ist nicht 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
Abschnitt betitelt „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)
Abschnitt betitelt „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,titleundtrailContextpro Step demonstriert:http://localhost:4321/demo/components/demo-scf-trail