Chainguard Academy

Our mission is to enable developers to build software efficiently and securely with Chainguard. Visit our website at 🔗 edu.chainguard.dev

You can find the educational resource files in Markdown under the content directory.

Development

This site is based on the Doks Hugo theme.

If you would like to develop this project, clone this repo and install dependencies with npm.

npm install

To run a local version of this site, use npm to start it.

npm run start

You'll then navigate to localhost:1313 within the web browser of your choice.

Testing

Any documentation published to Chainguard Academy is reviewed carefully for accuracy. GUI procedures, API commands, and CLI code snippets in a draft are run and tested thoroughly — by both the author and the reviewer — to confirm they work exactly as written. This helps ensure that readers can follow along and get the same results.

We also test drafts by previewing rendered content before it's published. Draft content passes through several checks between your editor and the live site:

• Local preview — Run npm install once, then npm run start to serve the site at http://localhost:1313 with live reload. Use this to confirm pages render correctly, formatting holds up, and internal links resolve. When a doc includes commands or examples, run them to confirm they still work.
• Pre-commit hooks — When you commit, automated hooks manage dates, validate tags, and spell-check your prose. See Pre-commit Hooks below for setup.
• Deploy previews — Every pull request builds a Netlify deploy preview with a staging URL. Reviewers open this link to see your changes rendered as they'll appear in production.

When you open a pull request, describe how you tested the change so reviewers know what to verify. Recent PRs often list the steps taken, such as previewing pages in the Hugo dev server, confirming links resolve, and running any commands the doc relies on.

📑 Contributing

If you identify something that is a major change, please file an issue. If you identify a minor change like a typo that needs to be updated, or tech tooling that has a newer package, you are welcome to open a pull request for review from the team.

Date Format

In each post's header, the date format should follow year-month-day as YYYY-MM-DD.

Adding Graphic Images

Please reduce the image's file size before adding the image to this project to make page load times faster and more accessible. You can use a tool such as TinyPNG.

If you are using images, it's best to bundle it together with the appropriate Markdown file. Create a directory with the name of the new page. Within the directory, create an index.md file and add the images within the directory as well.

In practice, this will look like the following, with images in place for both the getting-started-enforce-github directory and the install-enforce-github directory and the relevant tutorials:

├── chainguard
│   ├── _index.md
│   ├── enforce-github
│   │   ├── _index.md
│   │   ├── getting-started-enforce-github
│   │   │   ├── check.png
│   │   │   ├── index.md
│   │   │   ├── protected-branch.png
│   │   │   └── repo-access.png
│   │   └── install-enforce-github
│   │       ├── configure.png
│   │       ├── index.md
│   │       ├── permissions.png
│   │       └── user-select.png

Within the Markdown file, add images like so, with the alt text at the front:

![Protect branches with Chainguard Enforce](protected-branch.png)

Run a local development environment to ensure that your file structure is set up as intended.

Adding Videos

Use a liquid tag within the Markdown to embed a YouTube video. For example, if you would like to link to the YouTube video located at https://www.youtube.com/watch?v=rqIcDrg1XOs, you can pull the string after v= and use the following liquid tag on its own line within Markdown.

{{< youtube rqIcDrg1XOs >}}

Adding Tags

Tags are autogenerated when you add the following line to a Markdown file's front matter:

tags: ["Tag1", Tag2", etc]

This line should appear between the draft line and the images line in the front matter.

For example:

...
draft: false
tags: ["Chainguard Containers", "Overview", "Product"]
images: []
menu:
...

When applying tags, please make sure they conform to the working tag list below so that the tagging logic is consistent. If you'd like to add a new tag or suggest a tag revision, please submit a PR with a justification for the change.

Tags are based on:

• Content topics covered in the content, such as tools (Enforce, apko, etc), orgs/standards (OCI, SLSA, etc), and other relevant topics (SBOMs, etc).
• Content types represented by the content, such as procedural, conceptual, interactive, troubleshooting, etc.

You can review our current list of Tags.

Quick Reference for Contributors

Pre-commit Hooks

This repository uses automated pre-commit hooks to maintain content quality:

• Automatic date management - Adds date field to new files and updates lastmod when you edit
• Tag validation - Ensures tags match our approved taxonomy
• Spell checking - Catches typos before they're committed (ignores code blocks and technical terms)

Setup (one-time):

# Install spell checker
brew install aspell

# Enable hooks
./setup-hooks.sh

Resources:

• 📖 Complete Pre-commit Hook Guide for Contributors - Detailed guide with examples
• 📋 Tag Guidelines - Complete approved tag taxonomy
• 📝 Custom Dictionary - Technical terms for spell checker