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

📑 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

This repository uses the pre-commit framework to check changes before they merge. The pre-commit check is required on pull requests and runs only on the files a pull request changes (a pre-existing backlog is not gated). Run the same checks locally to catch problems before you push. They cover:

• Secret scanning, private keys, large files, and file hygiene such as trailing whitespace and end-of-file newlines
• GitHub Actions security (zizmor) and linting (actionlint)
• JavaScript (eslint), Markdown (markdownlint), SCSS (stylelint), and Python (bandit, black)
• Content tag validation against the approved taxonomy (advisory: it warns but never blocks a commit)
• Prose spell checking with aspell (advisory and local-only; skipped in CI)

One-time setup:

# 1. Install the pre-commit framework
brew install pre-commit        # or: pipx install pre-commit

# 2. Enable the repository's git hook
./setup-hooks.sh

# 3. If you edit SCSS (assets/scss/), install the Node dependencies
npm install

# 4. Optional: install aspell for local spell checking
brew install aspell

setup-hooks.sh points git at the .githooks/ directory. On each commit, that hook stamps date and lastmod on changed content files, then runs the pre-commit framework, so one hook covers everything. You don't need to run pre-commit install: git ignores .git/hooks once core.hooksPath is set, so a separately installed hook wouldn't run. To skip the hook for a single commit, use git commit --no-verify.

The SCSS lint step runs the project's own stylelint, so it needs the Node dependencies from npm install. The other hooks use pre-commit-managed environments, so they need nothing beyond the framework itself. If you edit assets/scss/ without installing the dependencies, that one hook fails; content and other contributors are unaffected.

Resources:

• Complete pre-commit hook guide for contributors — detailed guide with examples
• Tag guidelines — the approved tag taxonomy
• Custom dictionary — technical terms for the spell checker