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.
The site is built using:
- Astro with the Starlight docs theme
- Python, for
pull_external.py, which pulls documentation in from other SPIFFE repositories
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-serveThe 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-releasesThe 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.
Alternatively, you can run the website using the tools installed in your operating system.
You'll need:
First, install the dependencies:
$ make setupThen run the website:
$ make serve # or make serve-with-releasesThe website is now available at http://localhost:4175.
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.
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 websiteor
make check-links # if you are using a local toolchain to serve the websiteThe 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
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.
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.
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.
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 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 list of specifications on the Concepts page is generated using a YAML list in src/data/spec.yaml.
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.
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.
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.