Skip to content
Beta

Write and Publish an Asset

In 1 trail

Last updated on

An asset is one page that you write once and the Cloud Framework then shows everywhere it fits. This guide tells you where the file goes, what the frontmatter must say and how the checks treat it. Follow it and your page appears in the explorers, on the cards and in the trails without any extra work.


Every asset lives under docs/[framework]/assetcontainer/[partner-slug]/. The explorer reads the framework and the owner from this path.

  • Keep the path: If you move the file out of this structure, the automatic discovery no longer finds it. The asset then drops out of the overview maps.

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:


Copy this example as the start of a new asset:

---
title: "Compliant Asset Title"
# The description below is 150 characters: inside the rewarded window. Write your
# own summary of the page - the pipeline rejects placeholders and any description
# that quotes the length rule instead of describing the asset.
description: "Reference architecture for automated landing zone provisioning on STACKIT, covering network segmentation, IAM guardrails, and Terraform module layout."
scfAsset:
managed: true
# Required as soon as managed is true: the Marketplace entry this asset can be
# booked from. It has to be a marketplace.stackit.cloud address, the card renders
# no pill for anything else. No entry yet? Write
# https://marketplace.stackit.cloud/en/products as a stand-in. It holds for 7 days
# from the day this file is added; after that the weekly sweep tags the asset
# "wip" and it drops out of the default listing until somebody links the entry.
marketplaceUrl: "https://marketplace.stackit.cloud/en/products/<entry>"
category: "blueprint"
# Up to 10 tags, each at most 20 characters. Both limits are hard.
tags: ["cloud", "automation", "security"]
# Optional: credit the maintainers (shown as a point of contact).
maintainers:
- name: "Jane Doe"
role: "Cloud Architect"
# Optional: show a product logo instead of the contributor logo. Looks for
# this file in the contributor folder (contributors/<owner>/product.png) and
# for a light-product.png sibling next to it. Supply both, one per theme, the
# same way the contributor logo works. Without the light variant the card
# falls back to the contributor logo there and shows two different brands
# depending on the theme.
# productLogo: "product.png"
---

Section titled “Reference Links: <LinkCard> and <LinkChip>”

A link must say where it leads before anyone clicks it. Two components do that. In the files your PR touches the PR pipeline blocks every plain markdown link to another website and every link to another Cloud Framework page that is a line of its own:

  • <LinkCard> is a standalone panel for a reference that carries its own weight: the closing card at the end of an asset pointing to the repository or primary source, or a reference sitting under its own heading.
  • <LinkChip> is a compact inline pill for a link inside a sentence or inside a list: a link to another website in running text, a bullet that is only a link or a **Label**: followed by one.
<LinkCard title="Terraform Provider Documentation" href="https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs" />
- **Runbook**: <LinkChip href="/migration/migrate/">Migration execution phase</LinkChip>

Rules worth knowing:

  • A closing source card is recommended, not required. No gate checks that an asset has one. check-link-cards.mjs only checks the shape of the links you do write, so an open asset that documents everything in place is complete without any outbound link. The one hard link requirement lives in the frontmatter, not the body. A managed asset must carry marketplaceUrl. It has 7 days from the day it is added before the weekly sweep tags it wip for still standing on the placeholder. See the blueprint above.
  • No import needed. Both components are auto-imported in every content page.
  • The kind comes from the URL, never from you. Card and chip classify their href automatically as STACKIT portal, marketplace, documentation, code hosting or third party. A third-party destination is visibly marked as leading off the trail. There is no prop to override this, so a label can never lie about the destination.
  • A link to another Cloud Framework page inside a sentence stays a plain markdown link. The surrounding words already say where it leads. A link to another website becomes a chip there too: the chip shows what kind of site it leads to.
  • Code is exempt. Fenced blocks and inline code are commands and identifiers, not references. Same-page #anchors are navigation, not destinations.
  • On-site targets are resolved. The gate verifies that the page behind every on-site card and chip actually exists, so a typo in the path fails the pipeline instead of shipping a dead link.

STACKIT Documentation Sections: <ScfStackitExcerpt>

Section titled “STACKIT Documentation Sections: <ScfStackitExcerpt>”

Limits, plans, versions and model lists change on the STACKIT side. Do not copy them by hand. Point to the section of the STACKIT documentation instead. The page then shows it in a frame with its source and date. A scheduled run fetches every section four times a day, so the page stays current without anyone editing it.

<ScfStackitExcerpt href="https://docs.stackit.cloud/products/storage/file-storage/basics/limits/#general-limits" />
  • The address: the full English address of a page under https://docs.stackit.cloud/products/, with the #anchor of the heading where the section starts. The section runs to the next heading of the same level. The German page finds its German section by itself.
  • Finding the anchor: open the page in the STACKIT documentation and pick the heading in “On this page”. The address bar then ends in the anchor.
  • No import needed: the component is auto-imported like the link components.
  • A line of its own: put it on its own line with an empty line before and after. Never inside a list or a sentence.
  • When the docs change: the section follows after the next run. If the page moves or the anchor disappears, your page keeps the last checked version with its date. Framework Core gets a message with the new address.
  • On phones and in presentations: tables turn into cards on phones. Long tables are split over several slides. “Copy for AI” gets the section as text.
  • Good candidates: limits, plans, performance classes, version and end-of-life tables. Sections that are mostly product description or long step-by-step instructions are better as a <LinkCard>.
  • The model list: view="facts" profile="model-serving" shows the shared models of AI Model Serving as one table. It is the only profile today.

Run hike, summit or patrol as usual. New excerpts in your files are fetched for the preview and show the note “Local preview, not checked yet”. A wrong anchor is named in the terminal before the build, together with the anchors the page really has:

📄 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

The preview needs access to docs.stackit.cloud. Without it the build goes on and shows a placeholder. The preview of your pull request also shows a placeholder. After the merge the published page shows the section on the same day.


The explorer keeps its state in the address: the search, the filters and the open asset. Share the address and the other person sees the same view. These parameters are tracked:

  • Search: The search text is stored in lowercase in the search parameter.
  • Framework filter: The active framework filter is kept in the framework parameter.
  • Open asset: The asset that is open in the inline drawer is added as the asset parameter.

To put the explorer on a page, follow these steps.

  1. Import the Loader: Open the page file and import the asset loader.

    import ScfAssetLoader from '@components/scf/scf-asset-loader.astro';
  2. Place the Explorer: Add the component tag to the page. Pass frameworkSlug to start the view on one framework.

    <ScfAssetLoader frameworkSlug="migration"/>
  3. Check It Locally: Run the docs locally and check that the address changes when you search, filter or open an asset.


Live Component Playground (local dev server)

Section titled “Live Component Playground (local dev server)”

Run the docs locally (VS Code task 🥾 Hike — Start Dev Docs, or the hike command in the container terminal, served on http://localhost:4321) and open the interactive playgrounds below. Each page renders the component live and walks through every available configuration option, so it doubles as the authoritative reference for the props you can pass:

  • Asset Loader: every prop (frameworkSlug, showFilter, showSearch, assetIds, filterByTag, filterTagMode) with copy-paste examples for the global, curated, multi-tag and framework-filtered use cases. filterByTag takes one tag or an array to OR together; filterTagMode="all" requires all tags. Open http://localhost:4321/demo/components/demo-scf-loader
  • Asset Explorer: the interactive grid and list that the loader renders, including the inline detail drawer and deep-linking. Open http://localhost:4321/demo/components/demo-scf-explorer
  • Asset Card: a single card, with the framework label and the owner taken from the file path. Open http://localhost:4321/demo/components/demo-scf-card
  • Logo resolution: folder-based brand marks and the shared scf-core.png fallback. Open http://localhost:4321/demo/components/demo-scf-logos

Cloud Framework Explore the Cloud Framework Assets Explorer See every asset in the Cloud Framework, with search and filters. Open page
Asset historyActive 7 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 (17 more)