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
To develop the locally, you'll first need to install some assets (mostly Sass assets) using npm:
make setup
With those assets in place, you can run the site locally using Hugo or Docker.
Hugo
To run the site using Hugo, make sure it's installed and then run:
make serve
Check the
HUGO_VERSION
environment variable in thenetlify.toml
configuration file to see which Hugo version is deemed canonical for the SPIFFE website. Any Hugo version at or after that version should work fine. If you plan on working on the Sass/CSS, make sure to install the "extended" version of Hugo with support for Hugo Pipes, which processes the Sass in realtime.
Docker
If you have Docker installed, a convenient alternative to installing Hugo itself is to simply run:
make docker-serve
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 assets used to build the site are in a variety of directories and formats.
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 data/users.yaml
file. Make sure to add name
, description
(supports Markdown), logo
file (all logos should be added to static/img/logos
), and a link
to an external page.
Documentation
Markdown sources for the documentation are in the content
directory.
Latest SPIRE version
Hugo can automatically infer the latest version of SPIRE using the GitHub Releases API. To insert that version into text, use the spire-latest
shortcode.
This shortcode has a mandatory parameter that can be either version
, tag
or tarball
.
Here's an example:
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 content/downloads/_index.md
.
The SPIFFE specification
The Specification section of the main SPIFFE page is generated using a YAML list in data/spec.yaml
.
Shortcodes
Hugo has a feature called shortcodes that enables you to embed custom logic in Markdown files. The shortcodes for the site are in layouts/shortcodes
.
Acknowledgments
The shortcode for the "Acknowledgments" section of the Community page is in the acknowledgments.html
shortcode. To alter the contents of this section, update the data/acknowledgments.yaml
file.
Admonition blocks
There are four admonition blocks available for the site: info, danger, success, and warning. Here's an example:
{{< info >}}
Here's some important info regarding the SPIFFE project.
{{< /info >}}
Admonition blocks support Markdown.