Skip to content
Beta

Build a Trail Step by Step

In 1 trail

Last updated on

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.


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 scfTrail key. 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 +N chip. Every tag is searchable in the trail explorer.

Each step accepts an optional style key that marks its stage. The content schema accepts these values:

The style value is optional. Steps without it still render correctly.


A step shows either text that you write or a card that points at another page. Each type below has an example.

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."

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"

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"

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 sub with no preceding main is treated as a main step.
  • Foreign sources: if a sub-step points at a different assetId / pageId than 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 role is also the default agenda role when the trail is presented (see the Presentation guide), so sub steps 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."

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 (full says the same thing explicitly). right or left puts the picture beside the text instead.
  • imageWidth: the picture column’s width in percent for left / 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: 40

The 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: full

imageAlt 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 prose
  • assetId: "…": an asset card (a pointer). Add a #section-anchor to embed just that one section instead (the card is hidden by default; add cards: true to keep it).
  • pageId: "…": a page card (a pointer). Add a #section-anchor to embed just that one section instead (the card is hidden by default; add cards: true to 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:

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."

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, its trailContext text) is the default track. Nothing changes for existing trails: alternatives is 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: an assetId, a pageId (both may take a #section-anchor) or plain text from label + trailContext if there is neither.
  • label is the name shown in the chooser. For asset and page tracks it falls back to the referenced title.
  • An alternative’s own trailContext replaces 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."

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"

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."
---

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.


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.


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, title and trailContext: http://localhost:4321/demo/components/demo-scf-trail

Cloud Framework Explore the Trails Overview See every trail in the Cloud Framework and open one as a timeline or a slide deck. Open page
Asset historyActive 5 of the last 12 weeksTMUpdatedNo updates · 1 bar = 1 week i
Maintainer
TMTobias M.Head of STACKIT Cloud Framework · STACKITOwnerActive 11 of the last 12 weeks · 196 updatesSTACKITwww.linkedin.com/in/tobias-müller-011304172??Name not publicThe Cloud Framework team knows who this is. The name is not shown on the site.Contributed in STACKIT
Show full history (17 more)