--- title: "Asset Component Integration Guide" description: Der Asset Component Integration Guide erklärt, wie Asset-Discovery-Komponenten des STACKIT Cloud Framework Daten laden, Explorer steuern und State verwalten. scfAsset: category: "guide" tags: ["Components", "Astro", "Deep-Linking"] maintainers: - user: "tobias.mueller" source_url: "https://framework.stackit.cloud/de/advisory/assetcontainer/stackit/howto-asset-integration/" source_file: "docs/de/advisory/assetcontainer/stackit/howto-asset-integration.mdx" --- 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: ```markdown 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: ```json "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. | 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/`-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: ```markdown 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: ```markdown --- 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/" 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: `` und `` 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: - **``** 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. - **``** 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. ```mdx - **Runbook**: Migration execution phase ``` 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: `` 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. ```mdx ``` - **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 ``. - **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: ```text 📄 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. ```typescript 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. ```astro ``` 3. **Lokale Kompilierung prüfen**: Validiere die Umgebung, damit Browser-Parameter-Tracking und History-Hooks ohne Compilation-Warnungen funktionieren.