Ein Asset ist eine Seite, die du einmal schreibst und die das Cloud Framework dann überall zeigt, wo sie passt. Dieser Guide sagt dir, wo die Datei liegt, was das Frontmatter enthalten muss und wie die Prüfungen damit umgehen. Wenn du ihm folgst, erscheint deine Seite in den Explorern, auf den Karten und in den Trails, ohne dass du etwas dafür tun musst.
Wo Asset-Dateien liegen
Abschnitt betitelt „Wo Asset-Dateien liegen“Jedes Asset liegt unter docs/[framework]/assetcontainer/[partner-slug]/. Der Explorer liest das Framework und den Owner aus diesem Pfad.
- Pfad beibehalten: Wenn du die Datei aus dieser Struktur verschiebst, findet die automatische Discovery sie nicht mehr. Das Asset fehlt dann in den Übersichten.
Frontmatter-Felder und Regeln
Abschnitt betitelt „Frontmatter-Felder und Regeln“Der Build prüft das Frontmatter jedes Assets. Die Regeln unten sagen, was jedes Feld braucht. Eine Datei, die eine harte Regel verletzt, stoppt den Build.
- Description-Feld:
descriptionmuss eine echte, prägnante Zusammenfassung enthalten, denn sie erscheint auf der Asset-Karte und in Suchergebnissen. Ziel sind 120 bis 160 Zeichen: genug, um zu sagen, was das Asset bietet, und die Karte zeigt alles davon. Wird dieses Fenster getroffen, erhält das Asset einen Ranking-Bonus in der Explorer-Sortierung. Wird es verfehlt, kostet das nur den Bonus. Die Pipeline schweigt zwischen 120 und 180 Zeichen und warnt außerhalb davon, wo eine Description zu dünn wird oder auf der Karte abgeschnitten wird. Was die Pipeline stoppt: eine fehlende Description, ein Stummel unter 90 Zeichen, ein Platzhalter („TODO”, „description goes here”) oder eine Description, die die Längenregel zitiert, statt das Asset zu beschreiben. - Tags-Feld: Pro Asset sind maximal 10 Tags erlaubt, und jeder einzelne Tag darf 20 Zeichen nicht überschreiten. Drei oder mehr Tags zahlen ebenfalls auf den Ranking-Bonus ein.
Die Asset-Metadaten stehen unter dem Schlüssel scfAsset (analog zu scfTrail bei Trails). Der frühere Name frameworkAsset wird weiterhin akzeptiert, neue Assets sollten aber scfAsset verwenden. Optional lässt sich eine maintainers-Liste ergänzen, um die verantwortlichen Ansprechpartner auszuweisen (wird über der git-History angezeigt).
Maintainer würdigen
Abschnitt betitelt „Maintainer würdigen“maintainers nennt die Personen oder Organisationen, die dieses Asset pflegen und als Ansprechpartner dienen. Der Block erscheint als Maintainers über der Contributor-Liste der Git-Historie. Es ist eine Würdigung, keine Berechtigung: die Liste schränkt nicht ein, wer die Datei bearbeiten darf. Trails nutzen dasselbe Feld unter scfTrail.
Wer einen STACKIT-Git-Account hat, trägt sich nur mit dem Usernamen ein. Voller Name, Biography, Website und Adresse kommen aus dem eigenen Git-Profil, du pflegst sie also an einer Stelle statt in jedem Asset:
scfAsset: maintainers: - user: "jane.doe"Alles Weitere über dich steht an genau einer Stelle: docs/settings/contributor-members.json, gepflegt von Framework Core. Dort ist hinterlegt, zu welcher Contributor-Organisation du gehörst und welche deiner gespiegelten Profilfelder gezeigt werden dürfen: die Biography als Rollenzeile, deine Website, deine Adresse und dein Beitragsverlauf. Deshalb kann ein Asset nicht entscheiden, was über dich veröffentlicht wird. Freigeben kann nur die Person, die das Feld beschreibt, und ein Feld ohne Freigabe wird nie abgerufen und nie gespeichert.
Ein Eintrag sieht so aus:
"jane.doe": { "org": "acme-corp", "show": { "role": true, "website": true, "activity": true }}Auch deine Organisation kommt von dort. Deshalb schreibst du neben einem user kein contributor: niemand soll einen offiziellen Partner-Badge erben, indem er einen Firmennamen neben seinen eigenen tippt.
Ein role: true im Frontmatter eines Assets wirkt dagegen nicht mehr. Solche Zeilen aus der Vergangenheit werden weiterhin gelesen, bleiben aber wirkungslos und dürfen entfernt werden.
Deine Declaration
Abschnitt betitelt „Deine Declaration“Bevor irgendetwas über dich erscheint, auch dein Name, müssen zwei Dinge vorliegen: dein Eintrag in der Mitgliederdatei und die Declaration dahinter. In der Declaration erklärst du einmalig, was du zur Veröffentlichung freigibst: deine Marke, deine Inhalte und welche Angaben aus deinem Profil gezeigt werden dürfen.
Du legst sie selbst an. Öffne im Content-Repository ein Issue mit der Vorlage Contributor declaration und fülle sie aus. Eine Pipeline macht daraus eine vorgeschlagene Änderung an docs/settings/contributor-members.json, die Framework Core oder dein Framework Owner freigibt. Nichts aus dem Issue wird auf der Seite gerendert. Es ist der Nachweis dafür, was die Seite zeigen darf.
Solange dieser Nachweis fehlt, veröffentlicht die tägliche Pipeline nichts über dich, auch deinen Namen nicht, auch wenn die Freigaben in der Mitgliederdatei bereits gesetzt sind. Die Freigaben beschreiben, was du erlaubst. Die Declaration belegt, dass du es erlaubt hast, und die Pipeline wartet auf beides.
Für Änderungen gilt derselbe Weg: Reiche eine neue Declaration ein. Um alles zurückzuziehen, wähle die Vorlage Withdraw your declaration. Ein Kommentar auf deinem eigenen Declaration-Issue geht auch; Framework Core passt deinen Eintrag dann von Hand an.
Die Pipeline spiegelt die Profile einmal täglich und kopiert nur die Felder, die diese Person freigegeben hat: eine Website, eine Adresse oder eine Biography ohne Freigabe wird nie abgerufen und nie gespeichert. Dein Full Name braucht kein eigenes Häkchen: Die Declaration selbst gibt ihn frei, denn unter diesem Namen wirst du gewürdigt. Bis zur ersten Spiegelung zeigt der Eintrag deinen Usernamen, damit ein neuer Maintainer sofort gewürdigt wird statt in einer leeren Zeile zu stehen. Nach der Spiegelung gilt ein leerer Full Name als bewusste Entscheidung: Der Eintrag zeigt dann „Name nicht öffentlich”, statt deinen Usernamen offenzulegen. Wenn du lieber einen wiedererkennbaren Namen ohne deinen bürgerlichen Namen möchtest, trage im Full Name ein Pseudonym, eine Kurzform oder deine Initialen ein, und die Seite zeigt genau das.
Alle Felder
Abschnitt betitelt „Alle Felder“Jedes Feld ist einzeln optional und beliebig kombinierbar. Ein Eintrag braucht nur mindestens user, name, contributor oder email, damit er nie anonym gerendert wird; pro Asset sind bis zu 6 Einträge erlaubt.
| Feld | Zweck |
|---|---|
user | STACKIT-Git-Username. Schlüssel für das gespiegelte Profil und Rückfallanzeige, solange noch nichts gespiegelt wurde. |
role | Setzt den Rollentext wörtlich. Für Personen ohne Konto: bei einem user erscheint stattdessen die Biography aus dem eigenen Profil, und nur mit deren Freigabe. |
website | Setzt eine URL wörtlich, gleiche Regel wie role. |
email | Setzt eine Adresse wörtlich, gleiche Regel wie role. Sie erscheint als eigene Mail-Aktion und steht damit neben einem Profil-Link, statt mit ihm zu konkurrieren. |
name | Überschreibt den gespiegelten Namen und würdigt Personen ganz ohne Git-Account. Damit wird der Eintrag zur Person: Initialen-Avatar, Rollenzeile Rolle · Organisation. |
contributor | Slug eines /contributors/<slug>-Profils, für Personen ohne Konto. Allein gesetzt würdigt es die Organisation mit Profiltitel, Logo-Initialen und offiziellem Partner-Kennzeichen. Neben einem user wird es ignoriert, dessen Organisation kommt aus der Zuordnungsdatei. |
link | Ein Profil- oder Homepage-Link, typischerweise LinkedIn. Er hat Vorrang vor der gespiegelten Website und vor dem Contributor-Profil. |
Externe Partner haben keinen Account auf der Instanz und werden deshalb mit den expliziten Feldern gewürdigt:
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"Das Feld category im scfAsset-Block akzeptiert ausschließlich einen dieser zwölf vordefinierten Werte. Jeder andere Wert lässt den Build fehlschlagen:
| Kategorie | Zweck |
|---|---|
generic | Fallback für Assets ohne spezifische Kategorie. |
blueprint | Referenzarchitekturen und Lösungsdesigns. |
guide | Überblicke oder Schritt-für-Schritt-Installationsanleitungen. |
code-snippet | Wiederverwendbare Code-Teile (Terraform, YAML, CLI). |
policy | Governance, Security-Regeln und Compliance-Vorlagen. |
video | Visuelle Produktdemos oder Webinare. |
workshop | Materialien für Discovery-, Planungs- oder Migrations-Workshops. |
case-study | Erfolgsgeschichten und reale Umsetzungsbeispiele. |
whitepaper | Strategische Konzepte und tiefe technische Recherche. |
service | Professionelle oder Managed-Angebote (Consulting, Support, Betrieb). |
software | Einsatzfertige Anwendungen, Plattform-Erweiterungen oder Tools. |
runbook | Schritt-für-Schritt: Vorbereitung, Ausführung, Validierung, Rollback. |
Verwende diese konforme Metadaten-Vorlage, wenn du ein neues technisches Dokumentations-Asset in einen aktiven Workspace-Container aufnimmst:
---title: "Compliant Asset Title"# Die Description unten hat 150 Zeichen und liegt damit im belohnten Fenster.# Schreibe eine eigene Zusammenfassung der Seite - die Pipeline lehnt Platzhalter# und jede Description ab, die die Längenregel zitiert statt zu beschreiben.description: "Reference architecture for automated landing zone provisioning on STACKIT, covering network segmentation, IAM guardrails, and Terraform module layout."scfAsset: managed: true # Pflicht, sobald managed true ist: der Marketplace-Eintrag, über den das Asset # gebucht werden kann. Es muss eine marketplace.stackit.cloud-Adresse sein, für # alles andere rendert die Karte keine Pille. Noch kein Eintrag? Dann # https://marketplace.stackit.cloud/en/products als Platzhalter eintragen. Der # hält 7 Tage ab dem Tag, an dem die Datei angelegt wurde; danach setzt der # Wochenlauf das Asset auf "wip" und es fällt aus der Standardliste. marketplaceUrl: "https://marketplace.stackit.cloud/en/products/<entry>" category: "blueprint" # Bis zu 10 Tags, jeder höchstens 20 Zeichen. Beide Grenzen sind hart. tags: ["cloud", "automation", "security"] # Optional: Maintainer als Ansprechpartner ausweisen. maintainers: - name: "Jane Doe" role: "Cloud Architect"---Referenz-Links: <LinkCard> und <LinkChip>
Abschnitt betitelt „Referenz-Links: <LinkCard> und <LinkChip>“Ein Link muss sagen, wohin er führt, bevor jemand klickt. Zwei Komponenten leisten das. In den Dateien, die dein PR anfasst, blockiert die PR-Pipeline jeden einfachen Markdown-Link auf eine andere Website und jeden Link auf eine andere Seite des Cloud Framework, der eine eigene Zeile bildet:
<LinkCard>ist ein eigenständiges Panel für einen Verweis mit eigenem Gewicht: die Abschluss-Karte am Ende eines Assets, die auf das Repository oder die Primärquelle zeigt, oder ein Verweis unter einer eigenen Überschrift.<LinkChip>ist eine kompakte Inline-Pille für einen Link im Satz oder in einer Liste: ein Link auf eine andere Website im Fließtext, ein Bullet nur aus einem Link oder ein**Label**:gefolgt von einem Link.
<LinkCard title="Terraform Provider Documentation" href="https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs" />
- **Runbook**: <LinkChip href="/migration/migrate/">Migration execution phase</LinkChip>Die Regeln dahinter:
- Eine Abschluss-Karte auf die Quelle ist empfohlen, nicht verpflichtend. Kein Gate prüft, ob ein Asset eine hat.
check-link-cards.mjsprüft nur die Form der Links, die dastehen. Ein offenes Asset, das alles selbst mitbringt, ist ohne jeden ausgehenden Link vollständig. Die eine harte Link-Pflicht steht im Frontmatter statt im Body: ein gemanagtes Asset brauchtmarketplaceUrl, siehe die Vorlage oben. - Kein Import nötig. Beide Komponenten sind auf jeder Content-Seite automatisch importiert.
- Die Art kommt aus der URL, nie von dir. Karte und Chip klassifizieren ihren
hrefautomatisch als STACKIT-Portal, Marketplace, Dokumentation, Code-Hosting oder Drittanbieter. Ein Drittanbieter-Ziel wird sichtbar als Abzweig von der Route markiert. Es gibt kein Prop, das das übersteuert, damit ein Label nie über das Ziel täuschen kann. - Ein Link auf eine andere Seite des Cloud Framework mitten im Satz bleibt ein normaler Markdown-Link. Die umgebenden Wörter sagen bereits, wohin er führt. Ein Link auf eine andere Website wird auch dort ein Chip: Der Chip zeigt, zu welcher Art von Website er führt.
- Code ist ausgenommen. Code-Blöcke und Inline-Code sind Befehle und Bezeichner, keine Verweise, und
#anchorsauf derselben Seite sind Navigation, kein Ziel. - Interne Ziele werden aufgelöst. Das Gate prüft, dass die Seite hinter jeder internen Karte und jedem internen Chip wirklich existiert. Ein Tippfehler im Pfad lässt die Pipeline scheitern, statt einen toten Link auszuliefern.
Abschnitte aus der STACKIT-Doku: <ScfStackitExcerpt>
Abschnitt betitelt „Abschnitte aus der STACKIT-Doku: <ScfStackitExcerpt>“Limits, Pläne, Versionen und Modelllisten ändern sich auf der STACKIT-Seite. Schreib sie nicht von Hand ab. Verweise stattdessen auf den Abschnitt der STACKIT-Doku. Die Seite zeigt ihn dann in einem Rahmen mit Quelle und Datum. Ein Lauf holt jeden Abschnitt viermal am Tag, die Seite bleibt also aktuell, ohne dass jemand sie anfasst.
<ScfStackitExcerpt href="https://docs.stackit.cloud/products/storage/file-storage/basics/limits/#general-limits" />- Die Adresse: die volle englische Adresse einer Seite unter
https://docs.stackit.cloud/products/, mit dem#ankerder Überschrift, an der der Abschnitt beginnt. Er reicht bis zur nächsten Überschrift derselben Ebene. Die deutsche Seite findet ihren deutschen Abschnitt selbst. - Den Anker finden: Öffne die Seite in der STACKIT-Doku und wähle die Überschrift unter „On this page“. Die Adresszeile endet dann mit dem Anker.
- Kein Import nötig: Die Komponente ist wie die Link-Komponenten automatisch importiert.
- Eine eigene Zeile: Setz sie auf eine eigene Zeile, mit einer Leerzeile davor und danach. Nie in eine Liste oder einen Satz.
- Wenn sich die Doku ändert: Der Abschnitt folgt nach dem nächsten Lauf. Zieht die Seite um oder verschwindet der Anker, behält deine Seite den zuletzt geprüften Stand mit Datum. Framework Core bekommt eine Meldung mit der neuen Adresse.
- Am Handy und in Präsentationen: Tabellen werden am Handy zu Karten. Lange Tabellen werden auf mehrere Folien verteilt. „Copy for AI“ bekommt den Abschnitt als Text.
- Gute Kandidaten: Limits, Pläne, Performance-Klassen, Versions- und End-of-Life-Tabellen. Abschnitte, die vor allem Produktbeschreibung oder lange Schritt-für-Schritt-Anleitungen sind, passen besser als
<LinkCard>. - Die Modellliste:
view="facts" profile="model-serving"zeigt die Shared Models von AI Model Serving als eine Tabelle. Es ist bisher das einzige Profil.
Vorschau im Dev-Container
Abschnitt betitelt „Vorschau im Dev-Container“Starte wie gewohnt hike, summit oder patrol. Neue Abschnitte in deinen Dateien werden für die Vorschau geholt und tragen den Hinweis „Lokale Vorschau, noch nicht geprüft“. Ein falscher Anker wird vor dem Build im Terminal genannt, zusammen mit den Ankern, die es auf der Seite wirklich gibt:
📄 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-limitsDie Vorschau braucht Zugriff auf docs.stackit.cloud. Ohne ihn läuft der Build weiter und zeigt einen Platzhalter. Auch die Vorschau deines Pull Requests zeigt einen Platzhalter. Nach dem Merge zeigt die veröffentlichte Seite den Abschnitt noch am selben Tag.
Eine Ansicht per Link teilen
Abschnitt betitelt „Eine Ansicht per Link teilen“Der Explorer hält seinen Zustand in der Adresse: die Suche, die Filter und das geöffnete Asset. Teile die Adresse, und die andere Person sieht dieselbe Ansicht. Diese Parameter werden verfolgt:
- Suche: Der Suchtext steht in Kleinbuchstaben im Parameter
search. - Framework-Filter: Der aktive Framework-Filter steht im Parameter
framework. - Geöffnetes Asset: Das Asset, das im Inline-Drawer offen ist, steht im Parameter
asset.
Den Explorer in eine Seite einbauen
Abschnitt betitelt „Den Explorer in eine Seite einbauen“Um den Explorer in eine Seite einzubauen, folge diesen Schritten.
-
Loader importieren: Öffne die Seitendatei und importiere den Asset-Loader.
import ScfAssetLoader from '@components/scf/scf-asset-loader.astro'; -
Explorer platzieren: Füge das Komponenten-Tag in die Seite ein. Übergib
frameworkSlug, damit die Ansicht mit einem Framework startet.<ScfAssetLoader frameworkSlug="migration"/> -
Lokal prüfen: Starte die Doku lokal und prüfe, dass sich die Adresse ändert, wenn du suchst, filterst oder ein Asset öffnest.