README Components¶

Every captf-io repository’s README is composed from the same four components: a header, a badge row, a status note and a footer. They are plain HTML and Markdown that you copy into a README and fill in. No tool renders or syncs them, and no repository has its own images: the two images the components load are served by this site from https://captf.io/assets/readme/.

The components live in the website repository, captf-io/captf-io.github.io: the sources in includes/readme/, which this page embeds, and the images in docs/assets/readme/.

The README layout¶

A README puts the components around its own content in this order:

<header>

<badges>

<status note>

One paragraph: what this repository is and where it sits in CAPTF.

## Using it

## Developing

## Releasing

<footer>

The sections in the middle are the repository’s own. Keep to these rules so that the READMEs read the same:

• The header’s <h1> is the title, so the README has no # title line.
• Name sections with gerunds where they fit: Using it, Building…, Developing, Releasing. Reference sections such as Inputs and Outputs keep their nouns.
• Style the body with plain Markdown only: tables, fenced code with a language, and GitHub alerts ([!NOTE], [!TIP], [!WARNING]). The components carry all of the brand’s images, colour and HTML.
• No emoji, and no badges outside the badge row.
• Link to pages of other repositories and of this site with absolute URLs. A README that a registry also renders, such as a Terraform module’s, uses absolute URLs for its own files too.
• Write prose in the docs’ house style: plain, direct, present tense, with lines of at most 80 columns where the content allows.

Placeholders¶

Each component is written for one repository. Replace these placeholders when you paste it:

The workflows that the build badges report:

Header¶

The CAPTF mark, linked to the site, above the repository’s name, and the tagline under it. It is the first thing in the README.

<h1 align="center">
  <a href="https://captf.io/"><img
    src="https://captf.io/assets/readme/mark.svg"
    width="72" height="72" alt="CAPTF"></a>
  <br>
  REPO_NAME
</h1>

<p align="center">TAGLINE</p>

Badges¶

Build status, contract version, docs and license, under the header. Keep the order, and leave out the build badge only for a repository with no workflow on main. The shields use the site’s colours: 161B3A for the label and the brand’s purple, blue and yellow for the values.

<p align="center">
  <a href="https://github.com/captf-io/REPO_NAME/actions/workflows/CI_WORKFLOW"><img
    src="https://img.shields.io/github/actions/workflow/status/captf-io/REPO_NAME/CI_WORKFLOW?branch=main&amp;label=build&amp;labelColor=161B3A&amp;style=flat-square"
    alt="build"></a>
  <a href="https://captf.io/docs/module-author/contract/index.html"><img
    src="https://img.shields.io/static/v1?label=contract&amp;message=v1alpha1&amp;color=A974FF&amp;labelColor=161B3A&amp;style=flat-square"
    alt="contract v1alpha1"></a>
  <a href="https://captf.io/docs/"><img
    src="https://img.shields.io/static/v1?label=docs&amp;message=captf.io&amp;color=5B8CFF&amp;labelColor=161B3A&amp;style=flat-square"
    alt="docs captf.io"></a>
  <a href="https://github.com/captf-io/REPO_NAME/blob/main/LICENSE.md"><img
    src="https://img.shields.io/static/v1?label=license&amp;message=Apache-2.0&amp;color=FFD84D&amp;labelColor=161B3A&amp;style=flat-square"
    alt="license Apache-2.0"></a>
</p>

Status note¶

The pre-release note, under the badges. Every repository carries it while the API and the module contract are v1alpha1.

> [!NOTE]
> **Pre-release.** CAPTF is `v1alpha1`: its API and its
> [module contract](https://captf.io/docs/module-author/contract/index.html)
> may still change between releases.

Footer¶

A gradient divider, the mark, the site’s main links and the license, as the last thing in the README. It replaces a ## License section.

<br>
<p align="center">
  <img
    src="https://captf.io/assets/readme/divider.svg"
    width="100%" height="4" alt="">
</p>
<p align="center">
  <a href="https://captf.io/"><img
    src="https://captf.io/assets/readme/mark.svg"
    width="40" height="40" alt="CAPTF"></a>
  <br>
  <a href="https://captf.io/docs/"
    ><b>Documentation</b></a> ·
  <a href="https://captf.io/docs/getting-started/quick-start.html"
    ><b>Quick start</b></a> ·
  <a href="https://github.com/captf-io/.github/blob/main/CONTRIBUTING.md"
    ><b>Contributing</b></a> ·
  <a href="https://github.com/captf-io/.github/blob/main/SECURITY.md"
    ><b>Security</b></a>
  <br>
  <sub>Built for
    <a href="https://cluster-api.sigs.k8s.io/">Cluster API</a>.
    <a href="https://github.com/captf-io/REPO_NAME/blob/main/LICENSE.md"
    >Apache 2.0</a>.</sub>
</p>

Images¶

The components load their images from this site, so a change to one of them reaches every README once the site deploys.

Keep the file names: every README links to them. The mark has a dark tile of its own, unlike docs/assets/brand/mark.svg, so it reads on GitHub’s light and dark themes alike.

Changing a component¶

1. Edit the file in includes/readme/. This page embeds it, so the docs change with it.

2. Apply the same change by hand to every README that carries the component. From a workspace with every repository checked out side by side, list them with:

   grep -l 'captf.io/assets/readme/mark.svg' */README.md .github/README.md .github/profile/README.md
   

3. Commit the website change first and let it deploy when the change adds or renames an image; then commit the README in each repository.

To add a repository, copy the four components into its README and fill in the placeholders. There is nothing to register.