A trail chains assets, pages and your own text into one guided path. Readers follow it as a timeline. You can also present it as a slide deck.
Where Trail Files Live
Section titled “Where Trail Files Live”The loader registers a trail only if the file sits under the path below and carries the scfTrail key.
- Path: Save the trail file under this path in the content repository:
docs/[framework-slug]/trails/[contributor-slug]/[trail-slug].mdx- Required key: The frontmatter must include the
scfTrailkey. Without it the loader skips the file, so unfinished content stays hidden. - Optional tags: Add up to 10 tags under
scfTrail.tags(20 characters each at most) so people can find the trail. The card shows the first few plus a+Nchip. Every tag is searchable in the trail explorer.
Step Styles (style)
Section titled “Step Styles (style)”Each step accepts an optional style key that marks its stage. The content schema accepts these values:
| Style Key | Milestone Stage |
|---|---|
compass | PLAN: strategic alignment, assessments and migration discovery. |
hut | BASE: baseline environment setup and prerequisites. |
stairs | STEP: core engineering requirements and platform maturity. |
t-bar | LIFT (low): incremental enablement of capabilities. |
chairlift | LIFT (mid): scaling capabilities across teams. |
gondola | AUTO: continuous delivery and automated workflow pipelines. |
shield | SAFE: governance validation, security baselines and C5 compliance tracking. |
crevasse | WARN: risks, pitfalls and remediation checkpoints. |
chart | OPS: observability, cost and operational steering. |
rocket | LIVE: production launches and go-live milestones. |
summit | GOAL: milestone completion, handover and monitoring. |
The style value is optional. Steps without it still render correctly.
Step Types
Section titled “Step Types”A step shows either text that you write or a card that points at another page. Each type below has an example.
1. Text Steps
Section titled “1. Text Steps”Use a text step for an idea or a phase that has no page of its own yet. You write the title and the trailContext. The trailContext is the text the reader sees on the step. To write a step that works on a slide, see Write Steps That Work as Slides .
- style: "compass" title: "Assess the workloads before you build" trailContext: "Analyze the workload and its requirements before you create any resources."2. Asset Steps
Section titled “2. Asset Steps”Use an asset step to point at an asset by its assetId. The step shows the asset card with its contributor. Add an optional #section-anchor to the assetId to show only that section of the asset instead of the whole page, exactly like the page references below (for example .../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. Page Steps
Section titled “3. Page Steps”Use a page step to point at a regular framework page that is not an asset. Name it with its pageId. The step shows the page card and the page content right in the timeline. Add an optional #section-anchor to show only that section of the page instead of the whole page.
- 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"Nesting Steps as Sub-Points (role)
Section titled “Nesting Steps as Sub-Points (role)”Long trails often walk through several sections of the same source. Repeating the full step header (stage marker, asset card and contributor card) for each one buries the timeline. Give such a step role: sub and it nests as a compact, lettered row (a, b, …) under the nearest preceding main step. The row shows only its title and a one-line context, with no stage marker and no cards. Steps default to role: main, so existing trails are unchanged.
- Grouping: sub-steps attach to the main step above them. A
subwith no preceding main is treated as a main step. - Foreign sources: if a sub-step points at a different
assetId/pageIdthan its main step, a small source chip appears in the row. A slim source banner (logo · title · contributor · category · open link) is shown above its content, so the reader always knows where the content comes from. With the same source as the parent, nothing extra appears. - Expand all: a single button above the timeline opens or collapses every sub-step at once.
- Presentation link: a step’s
roleis also the default agenda role when the trail is presented (see the Presentation guide), sosubsteps come through as indented sub-points without extra work.
- style: "stairs" title: "The landing zone provisions the baseline" assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu" trailContext: "The accelerator provisions the baseline. The next rows walk its layers."- role: "sub" title: "The modules are broken down one by one" assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu#module-by-module-breakdown" trailContext: "Governance, connectivity and DevOps: what each module provisions."- role: "sub" title: "Account governance has its own page" pageId: "migration/design-and-mobilize/design/account-governance" trailContext: "A different source, so this row shows a source banner."Giving a Step Its Own Picture
Section titled “Giving a Step Its Own Picture”A step can carry a figure. In the timeline it appears under the step. In the presentation it becomes the slide’s second column or a full-width cover. Two fields control the layout in both cases:
imagePosition: leave it out and the picture is centered. It becomes a cover that spans the slide under the title, with the step text underneath (fullsays the same thing explicitly).rightorleftputs the picture beside the text instead.imageWidth: the picture column’s width in percent forleft/right(20 to 70, default 45). Ignored for centered covers.
Both fields are optional, so existing trails keep working unchanged.
The other column is whatever the step already shows as its content. You choose it with the fields you know: a trailContext paragraph, an asset section via assetId with a #section-anchor or a page section via pageId with a #section-anchor. So “image on the right, an asset section on the left” is just both fields on one step:
- style: "gondola" title: "Security topics accompany the 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 topics that accompany the Migrate phase" imagePosition: right imageWidth: 40The picture itself is named with imageSrc, a path relative to the content root, so you can keep the file next to your trail:
- style: "shield" title: "Security and compliance come before the first workload" trailContext: "The topic map below shows what has to be in place before the first workload moves." imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg" imageAlt: "Security and compliance topic map" imagePosition: fullimageAlt is both the alt text and the caption. Only pictures on this site are allowed. A path starting with / works too, but external http(s) addresses are ignored on purpose. Animated SVGs work: whatever animation is baked into the file plays in the timeline and on the slide.
Placing Content in Columns (left / right / center)
Section titled “Placing Content in Columns (left / right / center)”The picture fields above are the shortcut for “one content plus one image”. For full control over both sides, a step can place any content type into named slots, not just images. Each of left, right and center holds exactly one thing:
text: "…": free proseassetId: "…": an asset card (a pointer). Add a#section-anchorto embed just that one section instead (the card is hidden by default; addcards: trueto keep it).pageId: "…": a page card (a pointer). Add a#section-anchorto embed just that one section instead (the card is hidden by default; addcards: trueto keep it).trailId: "…": a trail card (a pointer to another trail).imageSrc: "…"(+imageAlt): a figure (click to zoom)
Card = pointer, #anchor = content. This is the key rule for columns: a bare assetId / pageId / trailId renders only the card. It is a compact pointer that says “here is the thing”. When you want the reader to actually see some of that content in the column, add a #section-anchor to an assetId or pageId. Exactly that one section is then embedded on its own. The card is hidden by default, so the column shows just the section. A compact origin breadcrumb Framework › Title stands in, so the reader still sees where it comes from. Trail cards are always pointers (a trail has no sections to embed). A whole asset or page body is too tall for a column. If you want the full content in the deck, reference it as a flat step (assetId / pageId at the step level, not in a column) instead.
Showing the card with cards: true. A step can stack several sections of the same source. A section column drops the card by default, so the card is not repeated in front of every section. When you do want the pointer card above the section, set cards: true on the column. The card then appears above the embedded content. The flag only matters when the column carries a section; a bare pointer always keeps its card so it never renders as an empty column.
Several items in one slot. left, right and center each also accept a list. The items stack in the given order inside that column, separated by a thin divider. They can come from different sources: three sections of one asset on the left, two pages on the right.
Where each slot renders:
| Frontmatter | Layout |
|---|---|
left: + right: | two columns side by side (split) |
left: only | that content in the left half, left-aligned |
right: only | that content in the right half, right-aligned |
center: | that content centered as a cover |
| none of these | the step renders exactly as before (backward compatible) |
Under ~900px the columns stack. For a split, splitRatio sets the left column’s width in percent (10 to 90, default 50). The timeline and the presentation slide use the same layout. What you compose here is what the deck shows.
# split: a page section on the left, an asset on the right, 55/45- style: "stairs" title: "Decision, then the tool that implements it" 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 on the left, a figure on the right- style: "shield" title: "Security topics come before the first workload" left: text: "Map the control topics before the first workload moves, not in the audit." right: imageSrc: "migration/design-and-mobilize/security-and-compliance/files/security-and-compliance-overview-map-en.svg" imageAlt: "Security and compliance topic map"
# center: a single cover figure (or centered text)- style: "chart" title: "The whole framework fits on one map" center: imageSrc: "advisory/trails/stackit/getting_started/map-overview.svg" imageAlt: "Framework overview map"
# several sections in one column: cards hidden by default, each under an origin breadcrumb- style: "stairs" title: "One runbook shows several sections side by side" 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: "Each section keeps its origin breadcrumb, so the reader can tell the three apart without three identical cards. Add cards: true to a column if you do want its pointer card shown."Alternative Steps (alternatives)
Section titled “Alternative Steps (alternatives)”Sometimes one stage of a journey has several equally valid ways to walk it: migrating the VMs with the standard guide, with a live-migration tool or with a replication tool. Without alternatives you would either build three steps for one decision or leave the alternatives out. With alternatives the step stays one waypoint (one title, one stage marker, one agenda entry). It carries several tracks the reader can switch between.
- The step’s own
assetId/pageId(or, with neither, itstrailContexttext) is the default track. Nothing changes for existing trails:alternativesis purely additive. - Each alternative needs a stable
id(deep links and presentation views key on it) and carries exactly one of the three content kinds a flat step can carry: anassetId, apageId(both may take a#section-anchor) or plain text fromlabel+trailContextif there is neither. labelis the name shown in the chooser. For asset and page tracks it falls back to the referenced title.- An alternative’s own
trailContextreplaces the step’s for that track. It is also that track’s speaker note in the presentation. - Limits: up to 4 alternatives per step. They work only on flat main steps. Sub steps (
role: sub) and column steps (left/right/center) do not support alternatives; the validator tells you if you try.
On the page the step renders its active track exactly like a normal step, with the track’s own asset and contributor cards. A quiet line under the cards (“2 alternatives for this step”) opens the chooser; picking a track swaps the cards and content in place. The choice lands in the URL as ?alt=<step-id>:<alternative-id> (comma-separated across steps), so a link can share a specific route. Give alternative steps an explicit step id for that. “Copy for AI” always exports the track that is currently shown and names the alternatives.
In the presentation the launch screen offers a track select for each alternative step (it starts with the track the page has active). A prepared view can pin a track via alternative: on its step reference. See the presentation guide below.
- 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."Complete Trail Example
Section titled “Complete Trail Example”Copy this example as the start of a new trail. You can add a maintainers list under scfTrail to credit who maintains the trail as a point of contact (shown above the git history). Assets use the same field.
If you have a STACKIT Git account, name yourself by username and nothing else. That is the whole entry:
scfTrail: maintainers: - user: "jane.doe"| Field | Purpose |
|---|---|
user | STACKIT Git username. The lookup key for the mirrored profile. It is also the fallback label until the profile has been mirrored. |
role | Sets the role text literally. For people without an account: with a user, the biography from their own profile appears instead, but only if they allowed it. |
website | Sets a URL literally, same rule as role. |
email | Sets an address literally, same rule as role. It renders as its own mail action, so it sits alongside a profile link instead of competing with it. |
name | Overrides the mirrored full name. It credits people who have no Git account. It makes the entry a person with an initials avatar and a role line reading role · organization. |
contributor | Slug of a /contributors/<slug> profile, for people without an account. On its own it credits the organization with the profile title, its logo initials and its official partner badge. Ignored next to a user, whose organization comes from the membership file. |
link | A profile or homepage URL, typically LinkedIn. It takes precedence over both the mirrored website and the contributor profile. |
Every field is optional and the fields combine freely. An entry only has to carry at least one of user, name, contributor or email. One trail accepts up to 6 entries. Keys the schema does not know are dropped without an error, so a typo leaves the build green and renders nothing. Maintainers are a credit, not a permission: the list does not restrict who may edit the trail. The asset integration guide carries the same fields with an example for external partners.
---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: credit the maintainers (shown as a point of contact above the git history). 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."---Reference Links in Supporting Pages
Section titled “Reference Links in Supporting Pages”A trail file itself is frontmatter-only, so the link rule never touches it. Text in trailContext and column text renders as plain text, links included. The rule does apply to the asset and content pages your steps point at. There, every reference that stands on its own line must be a <LinkCard> or <LinkChip>. Both are auto-imported and both derive their kind (portal, marketplace, documentation, code or third party) from the URL alone. The PR pipeline blocks bare standalone links in changed files and verifies that on-site card and chip targets exist. The full rule lives in the asset integration guide.
Presenting a Trail
Section titled “Presenting a Trail”Every trail can be opened as a slide deck from the presentation button on its detail view. No extra frontmatter is required. As the author you can also predefine prepared views (curated slide selections), preset the launch behavior and turn a step’s figure into a split slide. All of that lives in a presentations block under scfTrail and is documented in its own guide: the Presentation guide.
SCF Studio
Section titled “SCF Studio”To compose a trail without writing YAML by hand, use the SCF Studio. Start the docs (hike) and open /studio in your dev container, or use it on the dev site. It builds the steps and resolves every asset and page you point at. It can also load an existing trail and change only what you edit.
Live Component Playground (local dev server)
Section titled “Live Component Playground (local dev server)”Run the docs locally (VS Code task 🥾 Hike — Start Dev Docs or the hike command in the container terminal, served on http://localhost:4321) and open the interactive playgrounds below to see the trail components rendered live:
- Trail Loader: the auto-discovered, equal-height trail grid exactly as embedded via
<ScfTrailLoader />, including the inline detail view:http://localhost:4321/demo/components/demo-scf-trail-loader - Trail (single timeline): the full interactive milestone timeline with accordion asset cards. It shows how each step handles
style,assetId,titleandtrailContext:http://localhost:4321/demo/components/demo-scf-trail
Where to Go Next
Section titled “Where to Go Next”Asset historyActive 5 of the last 12 weeksTMUpdatedNo updates · 1 bar = 1 week i
- TMTobias M.Head of STACKIT Cloud Framework · STACKITOwner
Tobias M.Head of STACKIT Cloud Framework · STACKITOwnerActive 11 of the last 12 weeks · 196 updateswww.linkedin.com/in/tobias-müller-011304172