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.

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.

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 checks — A required pre-commit check validates tags, lints, and scans changed files; a git hook stamps content dates; spell-check runs locally. See Pre-commit 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.

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.

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

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.

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 >}}

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.

This repository uses the pre-commit framework to check changes before they merge. The pre-commit check is required on pull requests, and it runs only on the files a PR changes (a pre-existing backlog is not gated). It checks:

• Secret scanning, private keys, large files, and file hygiene (whitespace, EOF, line endings)
• GitHub Actions security (zizmor) and linting (actionlint)
• JavaScript (eslint), Markdown (markdownlint), and Python (bandit, black)
• Content tag validation against the approved taxonomy (blocking)
• Spell checking of prose with aspell — advisory and local-only (skipped in CI)

Setup (one-time):

# Install pre-commit
brew install pre-commit        # or: pipx install pre-commit

# Enable it in your clone
pre-commit install

# Optional: enable local prose spell checking
brew install aspell

Separately, a native git hook stamps date/lastmod on content files (it re-stages into the same commit, so it stays a git hook rather than a pre-commit hook). Enable it once with:

./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