--- title: "Your First Contribution: Profile, Asset, Trail" description: "Three stops to your first contribution: a profile that says who you are, an asset that carries what you know and a trail that chains your assets together." scfTrail: tags: ["getting-started", "contributing", "authoring"] maintainers: - user: "tobias.mueller" steps: - style: "compass" id: "overview" title: "Three Stops to Your First Contribution" trailContext: "A profile says who you are. Assets carry what you know. A trail turns them into a journey. The Studio helps with all three." imageSrc: "contributors/stackit/files/advisory/scf-onboarding.svg" imageAlt: "The route up the mountain: profile at the base, your asset in the explorer halfway up, the trail at the summit" - style: "hut" id: "create-profile" title: "One Page Introduces You" trailContext: "One page per organisation or person, added through a pull request like any other page. One review puts it live." splitRatio: 45 left: text: "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." right: imageSrc: "contributors/stackit/core/contributor-organisation.svg" imageAlt: "Putting your organisation into the directory: profile page, pull request, one review, the profile is live" - role: sub id: "files-location" title: "Where your files live" trailContext: "The folder layout for your profile, your assets and your logo files." assetId: "advisory/assetcontainer/stackit/howto-contributors#directory-structure--asset-placement" - style: "stairs" id: "asset-frontmatter" title: "Your Metadata Becomes the Card" trailContext: "Readers find the card in the explorer, filter by it and open the asset from there." splitRatio: 55 left: text: "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." right: assetId: "migration/assetcontainer/stackit/landing-zone-foundation-opentofu" - role: sub id: "asset-schema" title: "The metadata rules in full" trailContext: "Every field, its limits and the allowed categories." assetId: "advisory/assetcontainer/stackit/howto-asset-integration#strict-frontmatter-validation-schema" - style: "chairlift" id: "studio" title: "The Studio Writes the Metadata for You" trailContext: "The Studio runs in your dev container and on the dev site. It writes profiles, assets, trails and framework pages." splitRatio: 52 left: text: "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." right: imageSrc: "contributors/stackit/core/getting_started/studio.png" imageAlt: "The SCF Studio: a form on the right, the climb from page to page on the left" - style: "gondola" id: "configure-trail" title: "A Trail Turns Assets Into a Journey" trailContext: "The card on the right is the site tour, a trail built exactly this way." splitRatio: 42 left: text: "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." right: trailId: "advisory/trails/stackit/getting-started" - role: sub id: "trail-step-types" title: "The step types in detail" trailContext: "Text steps, asset steps and page steps, each with an example." assetId: "advisory/assetcontainer/stackit/howto-trail-setup#step-configuration-types" - style: "chart" id: "present-trail" title: "Your Trail Is Also a Slide Deck" trailContext: "Prepared views and speaker notes let one trail serve a workshop and a short briefing. Nothing to export, no second set of slides to keep up to date." splitRatio: 40 left: text: "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." right: imageSrc: "contributors/stackit/core/getting_started/present-trail.png" imageAlt: "The presentation icon in the top right of an open trail" - style: "summit" id: "publish-trail" title: "Your Part Ends With the Pull Request" trailContext: "Checks, preview and merge run without you once the pull request is open." splitRatio: 40 left: text: "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." right: imageSrc: "contributors/stackit/core/contribution-flow.svg" imageAlt: "Your part and the part that runs without you: fork, dev container, hike, patrol, pull request, then the automatic checks and the merge" - role: sub id: "trail-blueprint" title: "A complete trail to copy from" trailContext: "The full scfTrail block, ready to ship." assetId: "advisory/assetcontainer/stackit/howto-trail-setup#production-frontmatter-blueprint" presentations: - id: new-contributor label: "New contributor (with profile setup)" description: "The three stops for a first contribution: profile, asset and trail." default: true steps: - id: overview role: hidden notes: "Set the frame with the picture: three stops, profile at the base, the asset halfway up, the trail at the summit. The Studio helps with all three." - id: create-profile notes: "The profile is the public face: name, logo, short description. Created once through a normal pull request." - id: asset-frontmatter notes: "Point at the card on the right. Everything on it comes from the metadata block. Mention the 150 to 160 character window for the description; it is rewarded in the ranking." - id: studio role: sub notes: "Nobody has to write the metadata by hand. Show the Studio if you can: the checks run while you type, and it opens the pull request." - id: configure-trail notes: "Trails turn single assets into a story. The card on the right is the site tour, a trail like any other." - id: present-trail role: sub notes: "The meta moment: this deck is a trail. Mention prepared views and speaker notes." - id: publish-trail role: sub notes: "The pull request is the last thing they do. Automatic merge takes over after the review and green checks." - id: existing-contributor label: "Existing contributor (skip profile setup)" description: "For contributors who already have a profile: straight to assets and trails." steps: - asset-frontmatter - id: studio role: sub - configure-trail - id: present-trail role: sub - publish-trail - id: overview label: "Overview (non-technical)" description: "The contribution flow at a glance: profile, assets, trails and publishing, without the schema details." steps: - id: overview notes: "Every contributor owns a small, clearly bounded area: a profile, their assets, their trails. Nothing anyone contributes can touch another organisation's material." - id: create-profile notes: "The profile is the public face: name, logo, description. Every asset the organisation ships links back to it." - id: asset-frontmatter notes: "Every asset carries structured metadata, and automated checks keep it consistent. Quality is enforced by the pipeline, not by convention." - id: studio role: sub notes: "The built-in Studio writes valid files from a form. The technical setup exists for previewing, not as an entry barrier." - id: configure-trail notes: "Trails are the product: assets chained into a guided journey a customer can follow." - id: present-trail role: sub notes: "Every trail doubles as a slide deck for workshops and reviews. No second set of slides to maintain." - id: publish-trail notes: "Publishing is a reviewed pull request: automated checks plus a human review gate every change." source_url: "https://framework.stackit.cloud/advisory/trails/stackit/scf-onboarding/" source_file: "docs/advisory/trails/stackit/scf-onboarding.mdx" --- ## Steps ### 1. Three Stops to Your First Contribution Stage: `compass` A profile says who you are. Assets carry what you know. A trail turns them into a journey. The Studio helps with all three. ### 2. One Page Introduces You Stage: `hut` One page per organisation or person, added through a pull request like any other page. One review puts it live. ### 3. Where your files live The folder layout for your profile, your assets and your logo files. Asset: [/advisory/assetcontainer/stackit/howto-contributors/#directory-structure--asset-placement](/advisory/assetcontainer/stackit/howto-contributors/#directory-structure--asset-placement) — source: [/raw/advisory/assetcontainer/stackit/howto-contributors.md](/raw/advisory/assetcontainer/stackit/howto-contributors.md), section `#directory-structure--asset-placement` ### 4. Your Metadata Becomes the Card Stage: `stairs` Readers find the card in the explorer, filter by it and open the asset from there. ### 5. The metadata rules in full Every field, its limits and the allowed categories. Asset: [/advisory/assetcontainer/stackit/howto-asset-integration/#strict-frontmatter-validation-schema](/advisory/assetcontainer/stackit/howto-asset-integration/#strict-frontmatter-validation-schema) — source: [/raw/advisory/assetcontainer/stackit/howto-asset-integration.md](/raw/advisory/assetcontainer/stackit/howto-asset-integration.md), section `#strict-frontmatter-validation-schema` ### 6. The Studio Writes the Metadata for You Stage: `chairlift` The Studio runs in your dev container and on the dev site. It writes profiles, assets, trails and framework pages. ### 7. A Trail Turns Assets Into a Journey Stage: `gondola` The card on the right is the site tour, a trail built exactly this way. ### 8. The step types in detail Text steps, asset steps and page steps, each with an example. Asset: [/advisory/assetcontainer/stackit/howto-trail-setup/#step-configuration-types](/advisory/assetcontainer/stackit/howto-trail-setup/#step-configuration-types) — source: [/raw/advisory/assetcontainer/stackit/howto-trail-setup.md](/raw/advisory/assetcontainer/stackit/howto-trail-setup.md), section `#step-configuration-types` ### 9. Your Trail Is Also a Slide Deck Stage: `chart` Prepared views and speaker notes let one trail serve a workshop and a short briefing. Nothing to export, no second set of slides to keep up to date. ### 10. Your Part Ends With the Pull Request Stage: `summit` Checks, preview and merge run without you once the pull request is open. ### 11. A complete trail to copy from The full scfTrail block, ready to ship. Asset: [/advisory/assetcontainer/stackit/howto-trail-setup/#production-frontmatter-blueprint](/advisory/assetcontainer/stackit/howto-trail-setup/#production-frontmatter-blueprint) — source: [/raw/advisory/assetcontainer/stackit/howto-trail-setup.md](/raw/advisory/assetcontainer/stackit/howto-trail-setup.md), section `#production-frontmatter-blueprint`