StageFreight — Narrator & Badges¶

Narrator is StageFreight's content composition and injection system. It generates SVG badge assets, composes badges, shields, text, includes, and components into markdown, and injects them into managed marker sections in any document — your local README, Docker Hub descriptions, or any file referenced by config.

Reference docs: Config Reference — narrator · CLI Reference — narrator

How It Works¶

Narrator items are defined in the narrator: section of .stagefreight.yml. Each item has a kind that determines what it produces and a placement that declares where the output goes in the target file.

narrator:
  - file: "README.md"
    link_base: "https://github.com/myorg/myrepo/blob/main"
    items:
      - id: badge.release
        kind: badge
        placement:
          between: ["<!-- sf:badges:start -->", "<!-- sf:badges:end -->"]
          mode: replace
          inline: true
        text: release
        color: "#74ecbe"
        output: ".stagefreight/badges/release.svg"
        link: "https://github.com/myorg/myrepo/releases"

      - id: shield.pulls
        kind: shield
        placement:
          between: ["<!-- sf:badges:start -->", "<!-- sf:badges:end -->"]
          mode: replace
          inline: true
        shield: "docker/pulls/myorg/myrepo"
        link: "https://hub.docker.com/r/myorg/myrepo"

Items sharing the same placement markers are composed together — inline items are space-joined, block items are newline-joined.

Item Kinds¶

Kind	Purpose
`badge`	SVG badge image rendered from config (requires `output` for generation, `text` for label)
`shield`	Shields.io badge shorthand (path appended to `https://img.shields.io/`)
`text`	Literal markdown with template variable support
`component`	Pre-rendered component documentation from a spec file
`include`	Verbatim file inclusion (reads file content, inserts as-is)
`break`	Forces a line break between composed items

Badge¶

- id: badge.release
  kind: badge
  text: release            # left side label
  value: "{version}"       # right side (supports templates)
  color: "#74ecbe"         # hex or "auto" (status-driven)
  output: ".stagefreight/badges/release.svg"
  link: "https://..."      # click target

Badge SVGs are generated by stagefreight badge generate and referenced by narrator via the output path. Built-in fonts: dejavu-sans (default), vera, monofur, vera-mono, ethereal, playpen-sans, doto, penyae.

Shield¶

- id: shield.pulls
  kind: shield
  shield: "docker/pulls/myorg/myrepo"
  link: "https://hub.docker.com/r/myorg/myrepo"

Produces: [![pulls](https://img.shields.io/docker/pulls/myorg/myrepo)](https://...)

Text¶

- id: version-text
  kind: text
  content: "**Current version:** {version}"

Supports all template variables.

Include¶

- id: cli-reference
  kind: include
  path: docs/modules/cli-reference.md

Reads the file at path and inserts its content verbatim. No templating, no nested includes. Primary use case: assembling generated reference documentation into wrapper pages.

Component¶

- id: component-docs
  kind: component
  spec: "templates/my-component.yml"

Parses a GitLab CI component spec file and generates input documentation.

Break¶

- kind: break

Forces a new line. Items before the break are space-joined on one line, items after start a new line.

Placement¶

Placement declares where an item's output goes in the target file using between markers:

placement:
  between: ["<!-- sf:badges:start -->", "<!-- sf:badges:end -->"]
  mode: replace    # replace (default) | append | prepend | above | below
  inline: true     # space-joined (true) or newline-joined (false)

Content between markers is replaced idempotently on each run. Everything outside markers is never touched.

URL Resolution¶

Field	Resolved via	Purpose
Badge `output`	`raw_base` (derived from `link_base`)	Image source URL for SVG
`link` (relative)	`link_base`	Click target — rendered page URL
`link` (absolute)	used as-is	Absolute click target

raw_base is auto-derived from link_base:

Forge	`link_base`	Derived `raw_base`
GitHub	`github.com/{owner}/{repo}/blob/{branch}`	`raw.githubusercontent.com/{owner}/{repo}/{branch}`
GitLab	`gitlab.com/{owner}/{repo}/-/blob/{branch}`	`gitlab.com/{owner}/{repo}/-/raw/{branch}`
Gitea	`{host}/{owner}/{repo}/src/branch/{branch}`	`{host}/{owner}/{repo}/raw/branch/{branch}`

Template Variables¶

All narrator modules support template variables in text fields.

Template	Description
`{version}`	Full semantic version (e.g., `1.2.3`)
`{major}`, `{minor}`, `{patch}`	Semver components
`{sha}`, `{sha:N}`	Commit SHA (default 7, or N chars)
`{branch}`	Current branch name
`{var:name}`	User-defined variable from `vars:`
`{env:VAR}`	Environment variable value
`{date}`, `{datetime}`, `{timestamp}`	UTC date formats
`{date:FORMAT}`	Custom Go time layout
`{commit.date}`	HEAD commit date
`{project.name}`	Repo name from git remote
`{project.url}`	Repo URL (SSH to HTTPS conversion)
`{project.license}`	SPDX identifier from LICENSE file
`{docker.pulls}`, `{docker.stars}`	Docker Hub stats

CLI Commands¶

`narrator run` — Config-Driven¶

# Process all narrator items from .stagefreight.yml
stagefreight narrator run

# Dry-run to preview changes
stagefreight narrator run --dry-run

`narrator compose` — Ad-Hoc Shell Mode¶

stagefreight narrator compose -f README.md -s badges \
  badge:release,file:.stagefreight/badges/release.svg,link:https://... \
  shield:docker/pulls/myorg/myrepo,link:https://hub.docker.com/r/myorg/myrepo

See CLI Reference for full flag documentation.

Pipeline Integration¶

Narrator runs as part of the docs stage in CI:

stagefreight badge generate — renders all badge items to SVG files
stagefreight docs generate — generates CLI + config reference fragments
stagefreight narrator run — composes all items into target files (including assembling reference pages via kind: include)
stagefreight docker readme — syncs composed README to registries
stagefreight component docs — generates component documentation