IMPORTANT: Developer documentation for the current development branch. This content is unreleased, may change without notice, and must not be treated as Buildish release documentation.

Staged front matter types

Front matter and page-level metadata emitted into staged content.

Front matter and page-level metadata emitted into staged content.

Back to the reference overview.

Type index

ArtifactFrontMatterSummary

Small artifact summary embedded in component front matter.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key ArtifactKey yes Artifact key used to identify the artifact in page links and typed references.
displayName NonEmptyString no Human-readable artifact label shown in page chrome or listings.
latestStable VersionString no Most recent stable version that readers should treat as the default recommendation.
releaseLines list[ReleaseLineSummary] no Compact release-line summaries that the page can use for navigation or version selection.

Selected field examples

  • key: Example: "runtime"
  • displayName: Example: "Runtime"
  • latestStable: Example: "4.0.1"

PageSourceProvenance

Repository-neutral pointer to the authored source file for one staged page.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key SourceKey yes Resolved source-binding key that owns the authored page.
path RepoRelativePath yes Source file path relative to the resolved source binding root.
repository UrlString no Remote repository URL whose repository root corresponds to the resolved source binding root, when declared.
viewRef RefString no Source-control ref that renderers may use for a view-source link.
editRef RefString no Source-control ref that renderers may use for an edit-source link.

Selected field examples

  • key: Example: "runtime"
  • path: Example: "docs/getting-started.md"
  • repository: Example: "https://github.com/buildish-tooling/buildish-site-pipeline"
  • viewRef: Example: "main"
  • editRef: Example: "main"

PipelineComponentFrontMatter

Component-level pipeline metadata injected into staged page front matter.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
slug Slug yes Stable component slug for the owning component.
displayName NonEmptyString no Human-readable component name shown in page chrome or navigation.
latestStable VersionString no Most recent stable version recommended for the component as a whole when one shared release line is enough.
publication ResolvedPublication yes Resolved publication roots and URLs for the owning component.
artifacts list[ArtifactFrontMatterSummary] no Compact artifact summaries that pages can use for version navigation or page chrome.

Selected field examples

  • slug: Example: "spark"
  • displayName: Example: "Apache Spark"
  • latestStable: Example: "4.0.1"

PipelineFrontMatterNamespace

Reserved top-level front matter namespace that the pipeline injects into staged pages.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
component PipelineComponentFrontMatter no Component-level pipeline metadata injected into the staged page.
page PipelinePageFrontMatter no Page-local pipeline metadata injected into the staged page.

Example: Injected front matter for a component page and a released version.

 1component:
 2  slug: spark
 3  displayName: Apache Spark
 4  latestStable: 4.0.0
 5  publication:
 6    origin:
 7      key: archive
 8      baseUrl: https://archive.apache.org/dist/spark
 9      hostname: archive.apache.org
10    paths:
11      component: /spark/
12      development: /spark/main/
13      docs: /spark/docs/
14      assets: /spark/assets/
15    urls:
16      component: https://archive.apache.org/dist/spark/
17      development: https://archive.apache.org/dist/spark/main/
18      docs: https://archive.apache.org/dist/spark/docs/
19      assets: https://archive.apache.org/dist/spark/assets/
20page:
21  kind: docsPage
22  section: documentation
23  artifactKey: runtime
24  path: /spark/4.0.0/docs/getting-started/
25  url: https://archive.apache.org/dist/spark/4.0.0/docs/getting-started/
26  componentPath: /spark/
27  componentUrl: https://archive.apache.org/dist/spark/
28  version:
29    kind: released
30    label: 4.0.0
31    tag: v4.0.0
32  source:
33    key: runtime
34    path: docs/getting-started.md
35    repository: https://github.com/apache/spark
36    viewRef: main
37    editRef: main

PipelinePageFrontMatter

Page-local pipeline metadata injected into staged page front matter.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
kind NonEmptyString yes Short page kind label used by renderers to distinguish landing pages, docs pages, release notes, and similar page families.
section NonEmptyString no Optional higher-level section label that groups the page with related navigation or templates.
artifactKey ArtifactKey no Artifact key when the page belongs to one independently versioned artifact.
path PublicPath yes Published public path for this page.
url UrlString yes Canonical absolute URL for this page.
canonicalUrl UrlString no Explicit canonical URL when it should differ from url, for example to consolidate duplicate routes.
alternateUrls list[UrlString] no Additional absolute URLs that should be considered alternate entry points for the same page.
locale NonEmptyString no Locale key for this page when it participates in localization.
defaultLocale bool no Whether this page represents the default locale within its translation group.
translationKey NonEmptyString no Shared key that ties translated sibling pages together across locales.
derivedTitle NonEmptyString no Body-derived page title inferred from authored content when the pipeline can detect one.
derivedDescription NonEmptyString no Body-derived page description inferred from authored content when the pipeline can detect one.
translations list[TranslationLinkSummary] no Compact links to translated sibling pages in other locales.
componentPath PublicPath yes Public root path for the owning component.
componentUrl UrlString yes Absolute URL for the owning component root.
version VersionContext no Version or ref context attached when this page belongs to a versioned route set.
provider ProviderProvenance no Pointer back to the upstream provider record that informed the page’s version metadata.
source PageSourceProvenance no Repository-neutral provenance for the authored source file that produced this staged page.

Selected field examples

  • kind: Example: "docsPage"
  • section: Example: "documentation"
  • artifactKey: Example: "runtime"
  • path: Example: "/spark/4.0.0/docs/getting-started/"
  • locale: Example: "en"
  • translationKey: Example: "spark-overview"
  • derivedTitle: Example: "Getting Started"
  • derivedDescription: Example: "Install the package and run the quickstart."
  • componentPath: Example: "/spark/"

ProviderProvenance

Small pointer back to the provider record that informed this page’s version.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key ProviderKey yes Provider key for the upstream system that supplied the current version metadata.
externalId NonEmptyString no Provider-specific stable identifier for the upstream record that informed this page.
externalUrl UrlString no Human-browsable URL for the upstream record that informed this page.

Selected field examples

  • key: Example: "github-releases"
  • externalId: Example: "github:release:runtime-4.0.0"

ReleaseLineContext

Release-line context attached to one staged page’s current version.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key NonEmptyString yes Release-line key for this page’s version context.
supportStatus NonEmptyString no Support-status key or label associated with the current release line.
ancestors list[NonEmptyString] no Ancestor release-line keys ordered from nearest to farthest.
supportWindow SupportWindow no Lifecycle dates and support notes attached to the current release line.

Selected field examples

  • key: Example: "4.0"
  • supportStatus: Example: "supported"
  • ancestors: Example: ["4.x","stable"]

ReleaseLineSummary

Small release-line summary embedded into page or component front matter.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key NonEmptyString yes Release-line key, such as 4.0, for the summarized line.
parent NonEmptyString no Optional parent release-line key when lineage should be preserved in front matter.
latest VersionString no Latest released version currently associated with this line.
supportStatus NonEmptyString no Support-status key or label for the release line.
headRef RefString no Maintenance or line-head ref associated with this release line, if known.
aliases list[NonEmptyString] no Alternate labels that should also refer to this release line.
supportWindow SupportWindow no Lifecycle dates and support notes for the release line.

Selected field examples

  • key: Example: "4.0"
  • parent: Example: "4.x"
  • latest: Example: "4.0.1"
  • supportStatus: Example: "supported"
  • headRef: Example: "refs/heads/release-4.0"
  • aliases: Example: ["stable"]

ResolvedOrigin

Resolved origin details for the current publication target.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
key OriginKey yes Origin key selected for this published route or page.
baseUrl UrlString yes Fully qualified base URL for the selected origin.
hostname HostnameString yes Hostname extracted from baseUrl for callers that need it without reparsing the URL.

Selected field examples

  • key: Example: "archive"
  • baseUrl: Example: "https://archive.apache.org/dist/spark"
  • hostname: Example: "archive.apache.org"

ResolvedPathSet

Resolved public path roots for a component.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
component PublicPath yes Public root path for the component as a whole.
development PublicPath yes Public root path for development-version content.
docs PublicPath yes Public root path for versioned documentation content.
assets PublicPath yes Public root path for shared component assets.

Selected field examples

  • component: Example: "/spark/"
  • development: Example: "/spark/main/"
  • docs: Example: "/spark/docs/"
  • assets: Example: "/spark/assets/"

ResolvedPublication

Resolved origin, path roots, and absolute URLs for a component.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
origin ResolvedOrigin yes Origin details used to resolve paths into absolute URLs.
paths ResolvedPathSet yes Resolved public path roots for the component.
urls ResolvedUrlSet yes Resolved absolute URLs for the same publication roots.

ResolvedUrlSet

Resolved absolute URLs for a component.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
component UrlString yes Absolute URL for the component root.
development UrlString yes Absolute URL for the development-version root.
docs UrlString yes Absolute URL for the versioned docs root.
assets UrlString yes Absolute URL for the shared component asset root.

Selected field examples

  • component: Example: "https://archive.apache.org/dist/spark/"
  • development: Example: "https://archive.apache.org/dist/spark/main/"
  • docs: Example: "https://archive.apache.org/dist/spark/docs/"
  • assets: Example: "https://archive.apache.org/dist/spark/assets/"

TranslationLinkSummary

Compact link to one translated sibling page.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
locale NonEmptyString yes Locale key for the translated sibling page.
path PublicPath no Public path for the translated sibling page, if available.
url UrlString yes Absolute URL for the translated sibling page.
title NonEmptyString no Localized page title for the translated sibling page.

Selected field examples

  • locale: Example: "de"
  • path: Example: "/de/spark/overview/"
  • title: Example: "\u00dcbersicht"

VersionContext

Version, release-candidate, or ref context attached to one staged page.

  • category: emitted
  • ownership: pipeline-derived
  • file contract: (inner type)
Field Type Required Description
kind RecordKind yes Kind of version context attached to the page, such as release, candidate, development ref, or named ref.
label NonEmptyString yes Primary label shown to readers for this version context.
path PublicPath no Public route root for this version context when it has a routable landing path.
url UrlString no Absolute URL for the version-context route root when it has one.
docsPath PublicPath no Public docs root for this version context when versioned docs are available.
docsUrl UrlString no Absolute URL for the version-context docs root when it has one.
tag NonEmptyString no Exact tag name associated with this version context, if present.
ref RefString no Exact source-control ref associated with this version context, if present.
namedRefKey NonEmptyString no Catalog-authored named-ref key when this context represents a named ref.
publicationState PublicationState no Publication-state label for this version context, such as published or withdrawn.
maturity NonEmptyString no Maturity label such as preview, beta, or stable.
candidateSequence int no Release-candidate sequence number when this version context represents a candidate release.
voteStatus NonEmptyString no Vote status label for release-candidate contexts when it is known.
releaseLine ReleaseLineContext no Release-line context attached to the current version when the version belongs to a known release line.
supportWindow SupportWindow no Lifecycle dates and support notes attached directly to this version context.

Selected field examples

  • label: Example: "4.0.0"
  • path: Example: "/spark/4.0.0/"
  • docsPath: Example: "/spark/4.0.0/docs/"
  • tag: Example: "v4.0.0"
  • ref: Example: "refs/heads/main"
  • namedRefKey: Example: "preview"
  • maturity: Example: "stable"
  • candidateSequence: Example: 1
  • voteStatus: Example: "passed"