Skip to content
spiffePublic

About

Source for the SPIFFE and SPIRE project websites. Hosted by the Cloud Native Computing Foundation

Resources

Contributing

Stars

35 stars

Watchers

12 watching

Forks

Latest commit

 

History

1,153 Commits

Folders and files

Repository files navigation

spiffe.io

This repository contains the source for the SPIFFE website, currently hosted at https://spiffe.netlify.com. That website also contains the documentation for SPIRE, the SPIFFE Runtime Environment.

Toolchain

The site is built using:

Develop the site locally

Using Docker

This is the preferred way to run the website for local development as Docker is the only tool you need to install.

Ensure that Docker is running and then type:

$ make docker-serve

The first run takes a few minutes to build a Docker image with all the tools you need. After that, it serves the website at http://localhost:4175.

You can also run the website with a list of releases under the "SPIRE Releases" heading on the Downloads page (src/content/docs/downloads/index.mdx):

$ make docker-serve-with-releases

The default of make docker-serve omits the live SPIRE releases as a workaround to avoid a GitHub rate limiting issue as described in issue 93; version placeholders are shown instead. Set GITHUB_TOKEN to avoid the rate limit when including them.

Using your local environment

Alternatively, you can run the website using the tools installed in your operating system.

You'll need:

First, install the dependencies:

$ make setup

Then run the website:

$ make serve # or make serve-with-releases

The website is now available at http://localhost:4175.

Editing

Either way, the website runs in development mode: changes to the Markdown, data and static files, or to the external content descriptor file, rebuild the affected pages and reload them in your browser. Draft and future-dated pages are included, and are never published.

Pages are Markdown (or MDX, where they use components) under src/content/docs/, data files are in src/data/ and static files in public/. Pages pulled from other repositories are listed in the generated src/content/docs/.gitignore; the external-content contribution rules apply to them.

To build the site as Netlify does, run make build. The output is in dist/, and npm run preview serves it at http://localhost:4175. The build checks internal routes, fragments, aliases and the search index.

Checking for broken links

It is common that URLs you are pointing to get deprecated or moved somewhere else over time, leading to broken links on our website.

In order to avoid this, there is a tool that lets you check whether there are broken links in the whole website or not. It runs automatically on every pull request via the Link check GitHub Actions workflow, and you can also run it locally.

First, make sure you are serving the website locally with the releases included (make docker-serve-with-releases or make serve-with-releases), and that it is accessible at http://localhost:4175, then run the following command:

make docker-check-links # if you are using Docker to serve the website

or

make check-links # if you are using a local toolchain to serve the website

The tool will crawl your local website and report if there's any broken link on it. If there's any, and you can't create a PR to fix the link right away, please file an issue on GitHub

Publishing the site

The site is published automatically by Netlify. Whenever you merge pull requests to master, the site is automatically built and published in about a minute. There's no need to handle this manually.

Updating the site

The "Who uses SPIFFE?" section

The list of issuers and consumers in the "Who uses SPIFFE?" section of the home page is generated using the src/data/users.yaml file. Make sure to add name, description (supports Markdown), logo file (all logos should be added to public/img/logos), and a link to an external page.

Documentation

Markdown sources for the documentation are in src/content/docs/docs/latest/. Each directory is a sidebar group headed by its index page; pages are ordered by sidebar.order, then title, and labelled with sidebar.label if it is set. Old URLs that should keep working go in src/data/redirects.json.

Latest SPIRE version

The build fetches the latest version of SPIRE from the GitHub Releases API. To insert it into text, code blocks or link URLs, use one of these placeholders:

The most recent version of SPIRE is "SPIRE_LATEST_VERSION", that is tagged as "SPIRE_LATEST_TAG" and packed in the file "SPIRE_LATEST_TARBALL"

that will generate the following output:

The most recent version of SPIRE is "0.9.3", that is tagged as "v0.9.3" and packed in the file "spire-0.9.3-linux-x86_64-glibc.tar.gz"

The Downloads page

The Downloads page is built automatically using information from the GitHub Releases API. You can alter the text of the Downloads page in src/content/docs/downloads/index.mdx.

The SPIFFE specification

The list of specifications on the Concepts page is generated using a YAML list in src/data/spec.yaml.

Components

Pages that need generated content are MDX files that import a component from src/components/: SectionToc (the list of pages in a section), Ecosystem, Specs, Presentations and Releases.

Asides

Use Starlight's asides for notes and warnings: note, tip, caution and danger. For example:

:::note
Here's some important info regarding the SPIFFE project.
:::

Asides support Markdown.

Writing for the blog

The blog lives at /blog/ and is generated from Markdown under src/content/docs/blog/. Each post is a folder named YYYY-MM-DD-slug (the date prefix keeps posts ordered in the filesystem and becomes part of the URL) containing an index.md and any images it uses:

src/content/docs/blog/
  2026-06-19-my-post/
    index.md        # front matter + body
    diagram.png     # images live alongside the post

The fastest way to write a post is to copy the annotated example, src/content/docs/blog/2026-06-19-writing-a-blog-post/, rename the folder, and replace the contents. That post is a draft (so it only shows in local previews) and documents the front matter, images, tags, and publishing flow as it goes - read it for the full walkthrough. Posts are tagged with one or more of three tags: SPIFFE, SPIRE, and Community.

To preview locally, run the site (make docker-serve or make serve, both of which build drafts) and open http://localhost:4175/blog/. SEO metadata (title, description, canonical URL, Open Graph and Twitter Card tags) and the RSS feed are generated automatically; you don't need to add them by hand.

About

Source for the SPIFFE and SPIRE project websites. Hosted by the Cloud Native Computing Foundation

Resources

Contributing

Stars

35 stars

Watchers

12 watching

Forks

Releases

Packages

Used by

Contributors

Languages