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:
This is the preferred way to run the website for local development as Docker is the only tool you need to install and tool dependencies are managed better in the Docker method.
Ensure that Docker is running and then type:
$ make docker-serveThis command takes a few minutes to create a Docker image with all the tools you need to run the website. After that, it will serve the website locally. Note that some of the steps might ask you to run additional commands, please ignore them.
The following line indicates that the image has been created and the website is ready:
Web Server is available at //localhost:1313/ (bind address 0.0.0.0)
Open http://localhost:1313 in your browser to view your local version of the spiffe.io website.
The website is now running in development mode, meaning that any changes in the Markdown files or the external content descriptor file trigger a rebuild of the site. After the rebuild, the site is reloaded in your browser.
You can also run the website with a list of releases under the "SPIRE Releases" heading on the Downloads page (content/downloads/_index.md):
$ 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.
Alternatively, you can run the website in development mode using the tools installed in your operating system.
You'll need:
- Hugo (use HUGO VERSION, or higher)
- Python (use recommended version, or higher. Pyenv is recommended for version management)
- Pipenv
- npm
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.
First, you will have to install the dependencies running:
$ make setupThen you can run the website by typing:
$ make serve # or make serve-with-releasesHugo might take a few seconds to build and serve the website. The following line indicates that the website is ready:
Web Server is available at //localhost:1313/ (bind address 0.0.0.0)
The website is now available at http://localhost:1313. Changes in the Markdown files or the external content descriptor file trigger a rebuild of the site. After the rebuild, the site is reloaded in your browser.
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.
First, make sure you are serving the website locally using the -with-releases form of the script (make docker-serve-with-releases or make serve-with-releases), and that it is accessible at http://localhost:1313, 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 assets used to build the site are in a variety of directories and formats.
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.
Markdown sources for the documentation are in the content directory.
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 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 Specification section of the main SPIFFE page is generated using a YAML list in data/spec.yaml.
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.
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.
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.