Your First Contribution: Profile, Asset, Trail

PLAN

Three Stops to Your First Contribution

A profile says who you are. Assets carry what you know. A trail turns them into a journey. The Studio helps with all three.

The route up the mountain: profile at the base, your asset in the explorer halfway up, the trail at the summit

BASE

One Page Introduces You

Your profile is one page with your name, your logo and a short description. It goes in through a normal pull request. Every asset you ship links back to it.

Putting your organisation into the directory: profile page, pull request, one review, the profile is live

Work in the STACKIT Cloud Framework is attributed to a contributor, and a contributor is a profile page. These profiles control the dynamic rendering inside the interactive SCFContributorExplorer component and establish an explicit link between technical asset containers and the contributing organizations.

That does not mean everyone needs a page of their own. There are two ways in, and the right one depends on whether a company stands behind the work:

An organization contributes. Register it here. It earns its own page, a portfolio that collects every asset and trail it brings, and, once Framework Core has recorded the brand consent, its logo on every card. This guide is about that case.
A person contributes in their own name. Use the shared open-contributors entry instead of inventing an organization. Nothing else changes: assets and trails are filed under assetcontainer/open-contributors/ exactly as they would be anywhere else, and the same review applies. Because the entry is shared it carries no company mark, and the maintainers block on each page is what credits the individual — name yourself there with user: your.username.

Switching later is only a matter of moving the files: register the organization when it appears, and the pages move into its container.

Directory Structure & Asset Placement

The registration of a new contributor profile requires strict compliance with the STACKIT Cloud Framework repository conventions to protect responsive layouts on mobile screen sizes.

File System Paths

Profile Location: Create the contributor profile as an MDX file under the following exact repository path:

apps/docs/src/content/docs/contributors/[partner-slug].mdx

Asset Directory: Store all profile-specific media assets within a matching subfolder:

apps/docs/src/content/docs/contributors/[partner-slug]/

Corporate Identity Assets

Each theme carries its own file, and a theme without one shows a placeholder mark instead of borrowing the other. A logo drawn for white paper disappears on our dark surfaces, so we no longer stretch one file across both.

Dark mode logo: logo.png or logo.svg in the partner-specific subdirectory, 1:1 square aspect ratio. This is the file shown on the dark theme.
Light mode logo: light-logo.png or light-logo.svg, same folder and format rules. If your mark works on both grounds, supply the same artwork under both names.
What happens if one is missing: the theme without a file shows a neutral placeholder with your initials, never another company’s logo. Send the missing variant and it replaces the placeholder on the next build.

Technical Authoring & RAG Optimization Rules

To guarantee flawless compilation and high semantic visibility for automated Enterprise RAG indexers, follow these strict content design tokens:

SEO Recommendation: Write a real, concise summary into the frontmatter description field and aim for 120 to 160 characters: enough to say what the page offers. The card shows all of it. The window is rewarded with a ranking bonus rather than enforced: missing it costs the bonus and nothing else, and the pipeline only warns below 120 or above 180 characters. A missing description, a stub, or a placeholder fails the pipeline.
Lead-Term Pattern: All listings regarding competencies or core tech stacks must utilize the - **Lead term**: Explanation sentence. pattern to enforce HTML definition list rendering.
Context Splitting Prevention: Avoid using vague pronouns such as “it”, “they”, or “the platform”. Always explicitly state the partner name or the specific STACKIT service to keep vector database chunks completely self-contained.

Production Blueprint Example: Mockup Company

The following block represents a fully compliant reference implementation for a contributor profile. The layout utilizes the centralized <ScfContributorHeader /> component to automatically render brand marks and badges matching design system standards, replacing manual inline styling blocks.

---
title: "Mockup Company Inc."
description: "Official partner profile of Mockup Company Inc. – Specializing in sovereign cloud consulting, STACKIT infrastructure, and fully automated DevOps pipelines."
sidebar:
  hidden: true
---

<ScfContributorHeader title="Mockup Company Inc." badge="Consulting Partner" />

## Company Profile

Mockup Company Inc. guides organizations through the migration, modernization, and operation of workloads in sovereign cloud environments. As a core contributor to the STACKIT Cloud Framework, Mockup Company Inc. focuses on production-ready enterprise architectures, cloud automation, and compliance-driven cloud-native solutions.

## Consultant Profile

### Key Facts
- **Consultant Role**: Senior Cloud Consultant specializing in enterprise architecture.
- **Cloud Experience**: More than 4 years of dedicated project engineering experience.
- **Schwarz Gruppe History**: 8 years of total group experience including 2 years within the STACKIT ecosystem.
- **Academic Education**: Master of Science (M.Sc.) in Media Informatics.

### Technical Core Competencies

#### Cloud Platforms & Managed Services
- **STACKIT SKE**: Design, provisioning, and orchestration of production-ready managed Kubernetes clusters.
- **STACKIT Cloud Foundry**: Deployment, scaling, and lifecycle management of cloud-native applications.
- **Sovereign Cloud Compliance**: Architectural consulting aligned with Schwarz Gruppe governance and security directives.

#### Infrastructure as Code (IaC) & Automation
- **Terraform Automation**: Declarative provisioning and versioning of STACKIT resources including projects, networks, compute, and SKE.
- **Bash Scripting**: Automation of system processes, OS template preparation, and CI utility scripts.

#### DevOps, CI/CD & Tooling
- **Pipelining Engines**: Conception and implementation of robust CI/CD tracks for automated quality assurance and continuous deployment.
- **Docker Runtimes**: Construction of standardized container images and configuration of secure container runtimes.
- **Git Versioning**: Structured version control utilizing Git-Flow and Trunk-Based Development within distributed engineering teams.

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. Each renders the component live and documents its configuration options:

Contributor Loader — every prop (showSearch, contributorIds) with default and pre-filtered examples: http://localhost:4321/demo/components/demo-scf-contributor-loader
Logo resolution — how folder-based logo.png / light-logo.svg brand marks resolve per theme, and what the placeholder looks like when one is missing: http://localhost:4321/demo/components/demo-scf-logos

Central Directory Overview

Explore Registered Contributors

Return to the main directory to view all live, interactive contributor profiles and partner ecosystem maps.

STEP

Your Metadata Becomes the Card

An asset is one MDX page with a short metadata block: a title, a description of 150 to 160 characters, a category and up to 10 tags. The site turns it into this card.

Blueprint

STACKIT Landing Zone Accelerator

STACKIT

Migration design-and-mobilize landing-zone opentofu terraform +1

Open Source In 2 trails

STACKIT base asset for building a platform landing zone with reusable OpenTofu/Terraform modules, enterprise baseline patterns, and central Kubernetes.

Owner

STACKIT

The sovereign European cloud provider behind the framework, delivering IaaS and PaaS from German and Austrian data centers with full digital independence.

The STACKIT Cloud Framework provides a robust, decoupled architecture for discovering, scoring, and rendering technical architecture assets. This guide outlines the pipeline mechanics, data orchestration layers, and interactive state capabilities driving the automated asset discovery components.

Repository Storage Architecture

To ensure flawless automated ingestion, lifecycle indexing, and strict separation of framework governance, assets must be placed within explicit file system directories.

File System Path Rules

Authoritative Base Path: Every asset document must be stored under the standardized framework-specific structure: apps/docs/src/content/docs/[framework]/assetcontainer/[partner-slug]/.
Path Isolation: Moving or altering this path structure breaks the automatic workspace discovery pipelines and excludes the target asset from the global overview maps.

Strict Frontmatter Validation Schema

All asset configuration blocks must adhere to rigid schema validations to enforce search engine optimization (SEO) targets and robust Large Language Model (LLM) text chunk indexing constraints. Non-compliant files will trigger build-time compilation blocks.

Field Limits & Configurations

description: Must contain a real, concise summary. It is what readers see on the asset card and in search results. Aim for 120 to 160 characters: enough to say what the asset offers. The card shows all of it. Hitting that window earns the asset a ranking bonus in the explorer ordering. Missing it costs the bonus and nothing else. The pipeline stays quiet between 120 and 180 characters and warns outside that, where a description is too thin to say anything or gets cut off on the card. What does fail the pipeline: a missing description, a stub under 90 characters, a placeholder (“TODO”, “description goes here”), or a description that quotes the length rule instead of describing the asset.
tags: A maximum of 10 tags is allowed per asset. Each individual tag must not exceed 20 characters. Three or more tags also contribute to the ranking bonus.

The asset metadata block

Asset metadata lives under the scfAsset key (mirroring scfTrail for trails). The former name frameworkAsset is still accepted, so existing files keep working; new assets should use scfAsset. Optionally, add a maintainers list to credit who maintains the asset as a point of contact (shown above the git history).

Crediting Maintainers

maintainers names the people or organizations who look after this asset and act as its point of contact. It renders as a Maintainers block above the contributor list of the git history. It is a credit, not a permission: it does not restrict who may edit the file. Trails use the identical field under scfTrail.

If you have a STACKIT Git account, name yourself by username and nothing else. That is the whole entry:

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

Everything else about you lives in one place: settings/contributor-members.json, maintained by Framework Core. It records which contributor organization you belong to, and which of your mirrored profile fields may be shown: your biography as the role line, your website, your address, and your contribution record. That file is the reason an asset cannot decide what is published about you: only the person a field describes can grant it, and a field nobody granted is never even fetched.

Ask Framework Core to add or change your entry. It looks like this:

"jane.doe": {
  "org": "acme-corp",
  "show": { "role": true, "website": true, "activity": true }
}

Your organization comes from there too, which is why you do not write contributor next to a user: nobody should be able to inherit an official partner badge by typing a company name beside their own.

Your Declaration

Two things have to exist before anything beyond your name appears. Your entry in the membership file, and the declaration behind it. The declaration is where you state, once, what you release for publication: your brand, your content, and which of your profile details may be shown.

You file it yourself. Open an issue in the content repository and pick the Contributor declaration template, fill it in, and Framework Core or your framework owner records the result in settings/contributor-members.json. Nothing you write in the issue is rendered on the site. It is the record behind what the site is allowed to do.

Until that record exists, the daily pipeline publishes nothing about you, your name included, so the credit reads as an anonymous contributor even when the flags in the membership file are already set. The flags describe what you allow. The declaration is the proof that you allowed it. The pipeline waits for both.

The same route works later. Comment on your own declaration issue to change or withdraw any of it, and ask Framework Core or your framework owner to update your entry. A role: true in an asset does nothing, so there is no way to switch a field on from a content file. That is the point: only the person a field describes can release it.

The pipeline mirrors the profiles once a day and copies only the fields that person allowed: a website, an address or a biography nobody consented to is never fetched and never stored. Your full name is the exception, because it is the name you are credited under. Until your first mirror runs the entry shows your plain username, so a new maintainer is credited immediately rather than showing an empty row. Once mirrored, an empty Full name counts as a choice: the credit then reads “Anonymous contributor” instead of exposing your username. If you would rather keep a recognisable byline without your legal name, set the Full name to a pseudonym, a short form or your initials, and the site shows exactly that.

The Fields in Full

Every field is optional and they combine freely. An entry only has to carry at least one of user, name, contributor or email, so it is never rendered anonymously, and one asset accepts up to 6 entries.

Swipe sideways to see the whole table

Field	Purpose
`user`	STACKIT Git username. The lookup key for the mirrored profile, and the fallback label until it 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, and 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, and credits people who have no Git account at all. It makes the entry a person: initials avatar, role line reading role · organization.
`contributor`	Slug of a `/contributors/<slug>` profile, for people without an account. On its own it credits the organization, using 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 becomes the entry’s own link and takes precedence over both the mirrored website and the contributor profile.

External partners have no account on the instance, so they are credited with the explicit fields instead:

scfAsset:
  maintainers:
    - name: "John Smith"
      role: "Platform Engineer"
      contributor: "acme-corp"
      email: "john.smith@example.com"
      link: "https://www.linkedin.com/in/john-smith/"
    - contributor: "acme-corp"
      role: "Managed service"

Allowed Asset Categories (Enums)

The category field within the scfAsset configuration block only accepts one of these twelve predefined system enumerations. Any other value fails the build:

Swipe sideways to see the whole table

Category	Purpose
`generic`	Fallback for assets that fit no specific category.
`blueprint`	Reference architectures and solution designs.
`guide`	High-level overviews or step-by-step installation instructions.
`code-snippet`	Reusable code parts (Terraform, YAML, CLI).
`policy`	Governance, security rules, and compliance templates.
`video`	Visual product demonstrations or webinars.
`workshop`	Materials for discovery, planning, or migration workshops.
`case-study`	Success stories and real-world implementation examples.
`whitepaper`	Strategic concepts and deep technical research.
`service`	Professional or managed offerings (consulting, support, operations).
`software`	Ready-to-use applications, platform extensions, or tools.
`runbook`	Step-by-step preparation, execution, validation, and rollback instructions.

Production Frontmatter Schema Blueprint

Use this compliant metadata template when authoring or onboarding new technical documentation assets into an active workspace container:

---
title: "Compliant Asset Title"
# The description below is 150 characters: inside the rewarded window. Write your
# own summary of the page - the pipeline rejects placeholders and any description
# that quotes the length rule instead of describing the asset.
description: "Reference architecture for automated landing zone provisioning on STACKIT, covering network segmentation, IAM guardrails, and Terraform module layout."
scfAsset:
  managed: true
  # Required as soon as managed is true: the Marketplace entry this asset can be
  # booked from. It has to be a marketplace.stackit.cloud address, the card renders
  # no pill for anything else. No entry yet? Write
  # https://marketplace.stackit.cloud/en/products as a stand-in. It holds for 7 days
  # from the day this file is added; after that the weekly sweep tags the asset
  # "wip" and it drops out of the default listing until somebody links the entry.
  marketplaceUrl: "https://marketplace.stackit.cloud/en/products/<entry>"
  category: "blueprint"
  # Up to 10 tags, each at most 20 characters. Both limits are hard.
  tags: ["cloud", "automation", "security"]
  # Optional: credit the maintainers (shown as a point of contact).
  maintainers:
    - name: "Jane Doe"
      role: "Cloud Architect"
  # Optional: show a product logo instead of the contributor logo. Looks for
  # this file in the contributor folder (contributors/<owner>/product.png) and
  # for a light-product.png sibling next to it. Supply both, one per theme, the
  # same way the contributor logo works. Without the light variant the card
  # falls back to the contributor logo there and shows two different brands
  # depending on the theme.
  # productLogo: "product.png"
---

Reference Links: `<LinkCard>` and `<LinkChip>`

Every reference that stands on its own must say where it leads before anyone clicks it. Two components do that, and the PR pipeline blocks a bare markdown link on its own line in the files your PR touches:

<LinkCard> is a standalone panel for a reference that carries its own weight: the closing card at the end of an asset pointing to the repository or primary source, or a reference sitting under its own heading.
<LinkChip> is a compact inline pill for a link that is a line of its own inside a list — a bullet that is only a link, or a **Label**: followed by one.

<LinkCard title="Terraform Provider Documentation" href="https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs" />

- **Runbook**: <LinkChip href="/migration/migrate/">Migration execution phase</LinkChip>

Rules worth knowing:

A closing source card is recommended, not required. No gate checks that an asset has one. check-link-cards.mjs only checks the shape of the links you do write, so an open asset that documents everything in place is complete without any outbound link. The one hard link requirement lives in the frontmatter, not the body: a managed asset must carry marketplaceUrl, and it has 7 days from the day it is added before the weekly sweep tags it wip for still standing on the placeholder. See the blueprint above.
No import needed. Both components are auto-imported in every content page.
The kind comes from the URL, never from you. Card and chip classify their href automatically — STACKIT portal, marketplace, documentation, code hosting, or third party — and a third-party destination is visibly marked as leading off the trail. There is no prop to override this, so a label can never lie about the destination.
A link inside a sentence stays a plain markdown link. The surrounding words already say where it leads, and a chip there breaks the line for no gain.
Code is exempt. Fenced blocks and inline code are commands and identifiers, not references, and same-page #anchors are navigation, not destinations.
On-site targets are resolved. The gate verifies that the page behind every on-site card and chip actually exists, so a typo in the path fails the pipeline instead of shipping a dead link.

STACKIT Documentation Sections: `<ScfStackitExcerpt>`

Limits, plans, versions and model lists change on the STACKIT side. Do not copy them by hand. Point to the section of the STACKIT documentation instead. The page then shows it in a frame with its source and date. A scheduled run fetches every section four times a day, so the page stays current without anyone editing it.

<ScfStackitExcerpt href="https://docs.stackit.cloud/products/storage/file-storage/basics/limits/#general-limits" />

The address: the full English address of a page under https://docs.stackit.cloud/products/, with the #anchor of the heading where the section starts. The section runs to the next heading of the same level. The German page finds its German section by itself.
Finding the anchor: open the page in the STACKIT documentation and pick the heading in “On this page”. The address bar then ends in the anchor.
No import needed: the component is auto-imported like the link components.
A line of its own: put it on its own line with an empty line before and after. Never inside a list or a sentence.
When the docs change: the section follows after the next run. If the page moves or the anchor disappears, your page keeps the last checked version with its date. Framework Core gets a message with the new address.
On phones and in presentations: tables turn into cards on phones. Long tables are split over several slides. “Copy for AI” gets the section as text.
Good candidates: limits, plans, performance classes, version and end-of-life tables. Sections that are mostly product description or long step-by-step instructions are better as a <LinkCard>.
The model list: view="facts" profile="model-serving" shows the shared models of AI Model Serving as one table. It is the only profile today.

Preview in the dev container

Run hike, summit or patrol as usual. New excerpts in your files are fetched for the preview and show the note “Local preview, not checked yet”. A wrong anchor is named in the terminal before the build, together with the anchors the page really has:

📄 STACKIT excerpts: 2 request(s) for new references. What arrived shows "not checked yet" until the merge.
  /products/messaging/mailout/basics/resource-limits/#limits: no heading with this anchor. Anchors on that page: resource-limits, message-limits, sending-quota, object-resource-limits

The preview needs access to docs.stackit.cloud. Without it the build goes on and shows a placeholder. The preview of your pull request also shows a placeholder. After the merge the published page shows the section on the same day.

URL-Driven State Parameters

The explorer interface utilizes real-time history synchronization to ensure shared browser addresses act as immutable, reproducible application layouts. The state parameters are actively tracked:

Text filtering state: Sanitized lowercase text sequences are instantly stored via the search query parameter.
Framework isolation state: Specific active architectural category filter states are maintained via the framework query parameter.
Asset drawer tracking: Actively expanded inline technical documentation drawer components append the asset parameter to the address bar.

Production Integration Workflow

To implement the standardized discovery layout on an architectural landing view, utilize the sequential integration workflow.

Import the Execution Loader: Open the target page layout file and reference the authoritative build-time ingestion container directly.
```
import ScfAssetLoader from '@components/scf/scf-asset-loader.astro';
```
Mount the Interface Node: Embed the component tag inside the markup block. Pass an optional layout scoping value to lock the default interface view to a specific category.
```
<ScfAssetLoader frameworkSlug="migration"/>
```
Verify Local Compilations: Validate the environment to ensure that the browser parameter tracking and history hooks operate flawlessly without generating compilation warnings.

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. Each page renders the component live and walks through every available configuration option, so it doubles as the authoritative reference for the props you can pass:

Asset Loader — every prop (frameworkSlug, showFilter, showSearch, assetIds, filterByTag, filterTagMode) with copy-paste examples for the global, curated, multi-tag (filterByTag takes one tag or an array to OR together; filterTagMode="all" requires all), and framework-filtered use cases: http://localhost:4321/demo/components/demo-scf-loader
Asset Explorer — the interactive grid/list UI that the loader renders, including the inline detail drawer and deep-linking: http://localhost:4321/demo/components/demo-scf-explorer
Asset Card — single-card layout plus automatic framework-label and owner parsing from the file path: http://localhost:4321/demo/components/demo-scf-card
Logo resolution — folder-based brand marks and the shared scf-core.png fallback: http://localhost:4321/demo/components/demo-scf-logos

Central Overview

Explore the Cloud Framework Assets Explorer

Return to the main directory to view all live, interactive technical architecture components and managed code blocks.

LIFT

The Studio Writes the Metadata for You

Fill in a form. The SCF Studio checks every field while you type and opens the pull request for you. It also loads an existing page and changes only what you edit.

The SCF Studio: a form on the right, the climb from page to page on the left

AUTO

A Trail Turns Assets Into a Journey

A trail is a list of steps. Each step points at an asset, a page or one section of it. Add a picture or a second column and the step works as a slide too.

STACKIT

Getting Started with the Cloud Framework

Guided first tour of the STACKIT Cloud Framework site: read the mountain map, explore the frameworks, find assets, follow guided trails, and present them.

Advisory getting-started site-tour

Trail Steps

Welcome: One Map for Your Cloud Journey
The Six Frameworks: Pick Your Mountain
Example of a Built-Out Framework: Migration
Inside a Framework: The Core Modules

+ 8 more steps

Mapping out comprehensive migration paths connects scattered individual pieces into a single unified workspace experience. The core layout engine interprets structured parameters to build interactive timeline tracks for developers.

Folder Structure and Loading Requirements

For the system to automatically detect and register a journey path, your documents must follow precise workspace file paths.

Workspace Path Regulations

Target Storage Directory: Save your configuration file in the following specific directory path inside the workspace repository:

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

Required Configuration Property: The file header parameters must include the base scfTrail key. If this entry is missing, the indexing loader will automatically skip the document to ensure work-in-progress content stays hidden.
Optional Tags: Add up to 10 tags under scfTrail.tags (max 20 characters each) to make the trail discoverable. The card shows the first few plus a +N chip; every tag is searchable in the trail explorer.

Step Stage Styles (`style` enum)

Each timeline step accepts an optional style key that tags the milestone with its journey stage. These are the values validated by the content schema:

Swipe sideways to see the whole table

Style Key	Milestone Stage
`compass`	PLAN — strategic alignment, assessments, and migration discovery analysis.
`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 execution 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 Configuration Types

Timeline items can contain either custom descriptions or dynamic links to framework documents.

1. Descriptive Context Items

Perfect for steps that describe a high-level concept or phase where no physical code repository exists yet. Authors supply a custom title and a description field manually.

2. Connected Component Items

Points directly to a dynamic codebase example or pattern via its standard Astro ID. The core parser fetches the asset information, handles the creator data, and displays an interactive SCFAssetCard right on the milestone timeline track. Append an optional #section-anchor to the assetId to embed only that section of the asset instead of the whole document, exactly like the page references below (for example .../assetcontainer/stackit/howto-contributors#directory-structure--asset-placement).

3. Page Reference Items

Links a regular framework page (not an asset) via its pageId. The step renders an interactive SCFPageCard and embeds the page content directly in the timeline. Append an optional #section-anchor to render only that section of the page instead of the whole document, for example migration/migrate/#core-modules-in-this-phase.

Nesting Steps as Sub-Points (`role`)

Long trails often walk through several sections of the same source, and repeating the full step header (stage marker + asset card + 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 — just its title and a one-line context, 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 and 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. Same source as the parent = nothing extra.
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: "Provision the Landing Zone"
  assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"
  trailContext: "The accelerator provisions the baseline. The next rows walk its layers."
- role: "sub"
  title: "Module-by-module breakdown"
  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"
  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

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 — a cover that spans the slide under the title, with the step text following 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–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: "Run 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: "Anchor Security and Compliance Early"
  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`)

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 — 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, and exactly that one section is 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. Because a step that stacks several sections of the same source would otherwise repeat that card in front of every one of them, a section column drops the card by default. When you do want the pointer card above the section, set cards: true on the column and it 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, and they can come from different sources: three sections of one asset on the left, two pages on the right.

Where each slot renders:

Swipe sideways to see the whole table

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–90, default 50). The timeline and the presentation slide use the same layout, so 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: "Anchor Security Early"
  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 Terrain"
  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: "Three Steps of the Same Runbook"
  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`)

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) and 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, with neither, plain text from label + trailContext.
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, and 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 per alternative step (defaulting to whatever the page has active), and a prepared view can pin a track via alternative: on its step reference — see the presentation guide below.

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

Production Frontmatter Blueprint

Copy this metadata configuration layout as a baseline template when creating a new framework tracking timeline. Optionally add a maintainers list under scfTrail to credit who maintains the trail as a point of contact (shown above the git history), the same field assets use:

If you have a STACKIT Git account, name yourself by username and nothing else — that is the whole entry:

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

Swipe sideways to see the whole table

Field	Purpose
`user`	STACKIT Git username. The lookup key for the mirrored profile, and the fallback label until it 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, and 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, and credits people who have no Git account. It makes the entry a person: initials avatar, role line reading role · organization.
`contributor`	Slug of a `/contributors/<slug>` profile, for people without an account. On its own it credits the organization, using 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 they combine freely; an entry only has to carry at least one of user, name, contributor or email, and 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: "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."
---

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. It 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 auto-imported, both deriving their kind (portal, marketplace, documentation, code, 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

Every trail can be opened as a slide deck from the presentation button on its detail view — no extra frontmatter required. As the author you can also predefine prepared views (curated slide selections), preset the launch behaviour, 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

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, resolves every asset and page you point at, and it can load an existing trail and change only what you edit.

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, demonstrating per-step style, assetId, title, and trailContext handling: http://localhost:4321/demo/components/demo-scf-trail

Central Overview

Explore the Cloud Framework Trails Overview

Return to the main directory to view all live, interactive migration journeys and developer tracks.

OPS

Your Trail Is Also a Slide Deck

Press Present and the trail runs as a deck: on a projector, with a clicker or on a phone. You are watching one right now.

The presentation icon in the top right of an open trail

GOAL

Your Part Ends With the Pull Request

Tick automatic merge in the pull request. The checks, a preview site for the review and the merge run without you. The public site shows the change within two hours.

Your part and the part that runs without you: fork, dev container, hike, patrol, pull request, then the automatic checks and the merge

Mapping out comprehensive migration paths connects scattered individual pieces into a single unified workspace experience. The core layout engine interprets structured parameters to build interactive timeline tracks for developers.

Folder Structure and Loading Requirements

For the system to automatically detect and register a journey path, your documents must follow precise workspace file paths.

Workspace Path Regulations

Target Storage Directory: Save your configuration file in the following specific directory path inside the workspace repository:

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

Required Configuration Property: The file header parameters must include the base scfTrail key. If this entry is missing, the indexing loader will automatically skip the document to ensure work-in-progress content stays hidden.
Optional Tags: Add up to 10 tags under scfTrail.tags (max 20 characters each) to make the trail discoverable. The card shows the first few plus a +N chip; every tag is searchable in the trail explorer.

Step Stage Styles (`style` enum)

Each timeline step accepts an optional style key that tags the milestone with its journey stage. These are the values validated by the content schema:

Swipe sideways to see the whole table

Style Key	Milestone Stage
`compass`	PLAN — strategic alignment, assessments, and migration discovery analysis.
`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 execution 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 Configuration Types

Timeline items can contain either custom descriptions or dynamic links to framework documents.

1. Descriptive Context Items

Perfect for steps that describe a high-level concept or phase where no physical code repository exists yet. Authors supply a custom title and a description field manually.

2. Connected Component Items

Points directly to a dynamic codebase example or pattern via its standard Astro ID. The core parser fetches the asset information, handles the creator data, and displays an interactive SCFAssetCard right on the milestone timeline track. Append an optional #section-anchor to the assetId to embed only that section of the asset instead of the whole document, exactly like the page references below (for example .../assetcontainer/stackit/howto-contributors#directory-structure--asset-placement).

3. Page Reference Items

Links a regular framework page (not an asset) via its pageId. The step renders an interactive SCFPageCard and embeds the page content directly in the timeline. Append an optional #section-anchor to render only that section of the page instead of the whole document, for example migration/migrate/#core-modules-in-this-phase.

Nesting Steps as Sub-Points (`role`)

Long trails often walk through several sections of the same source, and repeating the full step header (stage marker + asset card + 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 — just its title and a one-line context, 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 and 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. Same source as the parent = nothing extra.
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: "Provision the Landing Zone"
  assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu"
  trailContext: "The accelerator provisions the baseline. The next rows walk its layers."
- role: "sub"
  title: "Module-by-module breakdown"
  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"
  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

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 — a cover that spans the slide under the title, with the step text following 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–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: "Run 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: "Anchor Security and Compliance Early"
  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`)

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 — 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, and exactly that one section is 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. Because a step that stacks several sections of the same source would otherwise repeat that card in front of every one of them, a section column drops the card by default. When you do want the pointer card above the section, set cards: true on the column and it 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, and they can come from different sources: three sections of one asset on the left, two pages on the right.

Where each slot renders:

Swipe sideways to see the whole table

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–90, default 50). The timeline and the presentation slide use the same layout, so 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: "Anchor Security Early"
  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 Terrain"
  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: "Three Steps of the Same Runbook"
  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`)

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) and 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, with neither, plain text from label + trailContext.
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, and 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 per alternative step (defaulting to whatever the page has active), and a prepared view can pin a track via alternative: on its step reference — see the presentation guide below.

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

Production Frontmatter Blueprint

Copy this metadata configuration layout as a baseline template when creating a new framework tracking timeline. Optionally add a maintainers list under scfTrail to credit who maintains the trail as a point of contact (shown above the git history), the same field assets use:

If you have a STACKIT Git account, name yourself by username and nothing else — that is the whole entry:

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

Swipe sideways to see the whole table

Field	Purpose
`user`	STACKIT Git username. The lookup key for the mirrored profile, and the fallback label until it 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, and 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, and credits people who have no Git account. It makes the entry a person: initials avatar, role line reading role · organization.
`contributor`	Slug of a `/contributors/<slug>` profile, for people without an account. On its own it credits the organization, using 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 they combine freely; an entry only has to carry at least one of user, name, contributor or email, and 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: "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."
---

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. It 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 auto-imported, both deriving their kind (portal, marketplace, documentation, code, 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

Every trail can be opened as a slide deck from the presentation button on its detail view — no extra frontmatter required. As the author you can also predefine prepared views (curated slide selections), preset the launch behaviour, 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

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, resolves every asset and page you point at, and it can load an existing trail and change only what you edit.

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, demonstrating per-step style, assetId, title, and trailContext handling: http://localhost:4321/demo/components/demo-scf-trail

Central Overview

Explore the Cloud Framework Trails Overview

Return to the main directory to view all live, interactive migration journeys and developer tracks.

Your First Contribution: Profile, Asset, Trail