Asset Component Integration Guide

Der Asset Component Integration Guide beschreibt die entkoppelte Architektur, mit der das STACKIT Cloud Framework technische Architektur-Assets erkennt, bewertet und rendert. Der Asset Component Integration Guide erläutert die Pipeline-Mechanik, die Daten-Orchestrierungs-Layer und die interaktiven State-Fähigkeiten hinter den automatisierten Asset-Discovery-Komponenten.

Repository-Speicherarchitektur

Die Asset-Pipeline des STACKIT Cloud Framework setzt für automatisierte Ingestion, Lifecycle-Indexierung und die strikte Trennung der Framework-Governance auf explizite Dateisystem-Verzeichnisse.

• Autoritativer Basis-Pfad: Jedes Asset-Dokument muss unter dem standardisierten, framework-spezifischen Pfad apps/docs/src/content/docs/[framework]/assetcontainer/[partner-slug]/ abgelegt werden.
• Pfad-Isolation: Das Verschieben oder Ändern der autoritativen Pfadstruktur unterbricht die automatische Workspace-Discovery-Pipeline und schließt das Ziel-Asset aus den globalen Übersichts-Maps aus.

Frontmatter-Validierungsschema

Jeder Asset-Konfigurationsblock des STACKIT Cloud Framework muss die Schema-Validierungen erfüllen, die SEO-Ziele und eine robuste Chunk-Indexierung für Large Language Models (LLM) durchsetzen. Nicht-konforme Dateien lösen Build-Time-Compilation-Blocks aus.

• Description-Feld: description muss 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

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: 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

Bevor mehr als dein Name erscheint, 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, fülle sie aus, und Framework Core oder dein Framework Owner trägt das Ergebnis in settings/contributor-members.json ein. Nichts aus dem Issue wird auf der Seite gerendert. Es ist der Nachweis dafür, was die Seite zeigen darf.

Solange dieser Nachweis fehlt, spiegelt die tägliche Pipeline nur deinen vollen Namen, 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. Kommentiere dein eigenes Declaration-Issue, um etwas zu ändern oder zurückzuziehen, und bitte Framework Core oder deinen Framework Owner, deinen Eintrag anzupassen.

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 ist die Ausnahme, 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 „Anonymous contributor”, 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

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.

Seitlich wischen, um die ganze Tabelle zu sehen

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"

Unbekannte Schlüssel verschwinden kommentarlos

Das Frontmatter-Schema verwirft Felder, die es nicht kennt, statt den Build abzubrechen. Bei einem Tippfehler bleibt der Build also grün, und es wird schlicht nichts angezeigt. Halte dich an die sieben Felder oben.

Das Feld category im scfAsset-Block akzeptiert ausschließlich einen dieser zwölf vordefinierten Werte. Jeder andere Wert lässt den Build fehlschlagen:

Seitlich wischen, um die ganze Tabelle zu sehen

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>

Jeder Verweis, der für sich steht, muss sagen, wohin er führt, bevor jemand klickt. Zwei Komponenten leisten das, und die PR-Pipeline blockiert einen nackten Markdown-Link auf eigener Zeile in den Dateien, die dein PR anfasst:

• <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, der in einer Liste eine eigene Zeile bildet — ein Bullet, das nur aus einem Link besteht, 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.mjs prü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 braucht marketplaceUrl, 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 href automatisch — STACKIT-Portal, Marketplace, Dokumentation, Code-Hosting oder Drittanbieter — und 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 mitten im Satz bleibt ein normaler Markdown-Link. Die umgebenden Wörter sagen bereits, wohin er führt, und ein Chip würde die Zeile ohne Gewinn zerteilen.
• Code ist ausgenommen. Code-Blöcke und Inline-Code sind Befehle und Bezeichner, keine Verweise, und #anchors auf 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>

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 #anker der Ü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

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-limits

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

URL-gesteuerte State-Parameter

Der Asset-Explorer des STACKIT Cloud Framework nutzt Echtzeit-History-Synchronisation, sodass geteilte Browser-Adressen als reproduzierbare Anwendungs-Layouts funktionieren. Der Explorer verfolgt drei State-Parameter:

• Text-Filter-State: Der Asset-Explorer speichert bereinigte Kleinbuchstaben-Textsequenzen im Query-Parameter search.
• Framework-Isolations-State: Der Asset-Explorer hält den aktiven Architektur-Kategoriefilter im Query-Parameter framework.
• Asset-Drawer-Tracking: Der Asset-Explorer hängt den aktuell ausgeklappten Inline-Dokumentations-Drawer an den Query-Parameter asset an.

Produktiver Integrations-Workflow

Um das standardisierte Discovery-Layout in eine Architektur-Landing-View einzubetten, folge dem sequenziellen Integrations-Workflow des STACKIT Cloud Framework.

1. Execution-Loader importieren: Öffne die Ziel-Layout-Datei und referenziere den autoritativen Build-Time-Ingestion-Container.

   import ScfAssetLoader from '@components/scf/scf-asset-loader.astro';

2. Interface-Node einbinden: Binde das Komponenten-Tag in den Markup-Block ein und übergib optional einen Layout-Scope, um die Standardansicht auf eine bestimmte Kategorie festzulegen.

   <ScfAssetLoader frameworkSlug="migration"/>

3. Lokale Kompilierung prüfen: Validiere die Umgebung, damit Browser-Parameter-Tracking und History-Hooks ohne Compilation-Warnungen funktionieren.