Skip to content
Beta

Your First Contribution: Profile, Asset, Trail

Last updated on

Stackit LogoStackit Logo
STACKIT

Your First Contribution: Profile, Asset, Trail

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.

PLAN

Three Stops to Your First Contribution

Assets carry what you know. A profile says who you are. You need one when an organisation stands behind the work. A trail is optional and turns assets into a journey. The Studio helps with all three.

From profile to trail The way up in three stages. At the base your profile, only for organisations. Halfway up your assets: guides, blueprints and code. At the top your trail, which is optional and chains assets into a path and a deck. From profile to trail WHO YOU ARE Your profile only for organisations WHAT YOU KNOW Your assets a guide or a blueprint THE JOURNEY Your trail optional, with a deck
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. Contributing in your own name? Skip this stop and use the shared open-contributors entry.

Registering a contributor organisation Registering a contributor organisation: fork and add the profile page, open a pull request, get one review, then the profile is live. Two panels below: the logo shows once Framework Core records brand consent and until then the card shows initials. Partner badge, recommendation and brand consent are set by Framework Core. Putting your organisation into the directory Add the profile page contributors/slug.mdx in your fork, like any page Pull request the same route and the same checks as any other change One review no special team is asked for the profile page itself The profile is live its own page plus a portfolio of everything it contributes Your logo comes later Commit logo.svg and light-logo.svg right away. Until Framework Core records brand consent your card shows your initials. Set by Framework Core Partner badge, recommendation and brand consent are set by Framework Core. Nobody grants them to themselves. No company behind the work? Then do not register one. Use the shared open-contributors entry instead.
Putting your organisation into the directory: profile page, pull request, one review, the profile is live
STACKIT LogoSTACKIT Logo
Register a Contributor Profile STACKIT · Guide Open asset ↗

The file name of your profile is your contributor slug. Assets, trails and logos find your profile through this slug. Your assets sit under assetcontainer/[partner-slug]/. The logo is found in the profile folder with the same name.

  • Profile Location: Create the contributor profile as an MDX file under the following exact repository path:
docs/contributors/[partner-slug].mdx
  • Asset Directory: Store all profile-specific media assets within a matching subfolder:
docs/contributors/[partner-slug]/

Each theme carries its own file. 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 one file no longer serves both themes.

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

STEP

Your Metadata Becomes the Card

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

STACKIT LogoSTACKIT Logo
Write and Publish an Asset STACKIT · Guide Open asset ↗

The build checks the frontmatter of every asset. The rules below say what each field needs. A file that breaks a hard rule stops the build.

  • 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. Outside that range it warns, because 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.

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

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: docs/settings/contributor-members.json, maintained by Framework Core. It records which contributor organization you belong to. It also records 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. 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.

Two things have to exist before anything about you appears, your name included. These are 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 and your content. It also says which of your profile details may be shown.

You file it yourself. Open an issue in the content repository, pick the Contributor declaration template and fill it in. A pipeline turns it into a proposed change of docs/settings/contributor-members.json, which Framework Core or your framework owner approves. 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 “Name not public” 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. To change what is shown, file a new declaration. To withdraw everything, pick the Withdraw your declaration template. A comment on your own declaration issue works too; Framework Core then updates your entry by hand. 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 needs no box of its own: the declaration itself releases it, 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 “Name not public” 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. The site then shows exactly that.

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. One asset accepts up to 6 entries.

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"

The category field in the scfAsset block accepts one of these twelve values. Any other value fails the build:


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 leftThe SCF Studio: a form on the right, the climb from page to page on the left
The SCF Studio: a form on the right, the climb from page to page on the left
STACKIT LogoSTACKIT Logo
Build a Trail Step by Step STACKIT · Guide Open asset ↗

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"

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 trailThe presentation icon in the top right of an open trail
The presentation icon in the top right of an open trail
GOAL

Your Part Ends With the Pull Request

Open the pull request. The checks run in the background. Tick the preview box and a password-protected preview site goes up for the review. Tick automatic merge and the merge follows the approval. The public site shows the change within two hours.

What you do and what runs in the background Five stations. You write, preview and submit the pull request. In the background Framework Core reviews it and the page goes live. If changes are asked for you go back to writing. Checks and an optional preview site run on every push. What you do and what runs in the background YOU Write Studio or editor Preview see your page Submit open the pull request IN THE BACKGROUND Review by Framework Core Live within two hours Checks and an optional preview site run on every push Changes asked for? Fix them on the same branch. Merges by itself after approval if you tick automatic merge.
The route in five stations: Write, Preview, Submit, Review, Live, with the checks running in the background
STACKIT LogoSTACKIT Logo
Build a Trail Step by Step STACKIT · Guide Open asset ↗

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

Trail historyActive 4 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 (14 more)