Zum Inhalt springen
Beta

Dein erster Beitrag: Profil, Asset, Trail

Zuletzt aktualisiert am

Stackit LogoStackit Logo
STACKIT

Dein erster Beitrag: Profil, Asset, Trail

Drei Stationen zu deinem ersten Beitrag: ein Profil, das sagt, wer du bist, ein Asset mit deinem Wissen und ein Trail, der deine Assets verbindet.

PLAN

Drei Stationen zu deinem ersten Beitrag

Assets tragen, was du weißt. Ein Profil sagt, wer du bist, und du brauchst eines, wenn eine Organisation hinter der Arbeit steht. Ein Trail ist optional und macht aus Assets eine Journey. Das Studio hilft bei allen dreien.

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
Die Route auf den Berg: das Profil am Fuß, dein Asset im Explorer auf halber Höhe, der Trail am Gipfel
BASE

Eine Seite stellt dich vor

Dein Profil ist eine Seite mit deinem Namen, deinem Logo und einer kurzen Beschreibung. Sie kommt über einen normalen Pull Request hinein. Jedes Asset von dir verweist darauf zurück. Du trägst in eigenem Namen bei? Dann lass diese Station aus und nutze den geteilten Eintrag open-contributors.

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.
Deine Organisation ins Verzeichnis bringen: Profilseite, Pull Request, ein Review, das Profil ist online
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

Aus deinen Metadaten wird die Karte

Ein Asset ist eine MDX-Seite mit einem kurzen Metadatenblock: ein Titel, eine Beschreibung mit 120 bis 160 Zeichen, eine Kategorie und bis zu 10 Tags. Daraus baut die Seite diese Karte.

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

Das Studio schreibt die Metadaten für dich

Du füllst ein Formular aus. Das SCF Studio prüft jedes Feld schon beim Tippen und öffnet den Pull Request für dich. Es lädt auch eine bestehende Seite und ändert nur, was du bearbeitest.

Das SCF Studio: rechts ein Formular, links der Aufstieg von Seite zu SeiteDas SCF Studio: rechts ein Formular, links der Aufstieg von Seite zu Seite
Das SCF Studio: rechts ein Formular, links der Aufstieg von Seite zu Seite
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

Dein Trail ist auch ein Foliendeck

Klicke auf Präsentieren, und der Trail läuft als Deck: am Beamer, mit einem Klicker oder am Handy. Du siehst gerade eines.

Das Präsentations-Icon oben rechts in einem geöffneten TrailDas Präsentations-Icon oben rechts in einem geöffneten Trail
Das Präsentations-Icon oben rechts in einem geöffneten Trail
GOAL

Dein Teil endet mit dem Pull Request

Öffne den Pull Request. Die Prüfungen laufen im Hintergrund. Mit dem Haken für die Vorschau geht eine passwortgeschützte Vorschauseite für das Review online. Mit dem Haken für den automatischen Merge folgt der Merge der Freigabe. Die öffentliche Seite zeigt die Änderung innerhalb von zwei Stunden.

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.
Der Weg in fünf Stationen: Schreiben, Vorschau, Einreichen, Review, Live, mit den Prüfungen im Hintergrund
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."
---