eks-workshop: a Hugo site that teaches EKS, maintained in place

A workshop site, not a tool you install and run

eks-workshop is the source behind eksworkshop.com, a set of hands-on labs for learning Amazon EKS. The repository describes itself as the AWS Workshop for Learning EKS, and the primary language recorded for it is CSS, which tells you more about the shape of the project than the topic list does. What lives here is a static site: Markdown chapters under content/, Hugo templates, layouts, static assets and a config.toml, with the site build producing a directory of HTML that is uploaded to S3.

So there is no binary to install and no cluster to provision from this repository. The value is in the written labs, the supporting YAML and shell snippets, and the deployment pipeline that keeps the published version in step with the source. That distinction matters if you came looking for infrastructure code, because the repository root holds a theme submodule, an amplify.yml and a disabled buildspec rather than Terraform modules.

The intended reader is someone learning EKS concepts by following a step, then trying that step by hand in their own account. Everything is arranged around that reading flow, which is why the site structure and the content structure are so tightly coupled.

The theme lives in a submodule, and a plain clone will not build it

The first mechanical thing a contributor hits is the themes/ directory. It is a git submodule, and the documentation is explicit that it has to be initialised separately. A clone without that step gives you a site with no theme and therefore no layouts.

From a checkout, the sequence is a clone, a move into the directory, then the two submodule commands:

git clone [email protected]:aws-samples/eks-workshop.git
cd eks-workshop
git submodule init
git submodule update

The npm package exposes the same pair as a single script named theme, which is what the Gitpod setup instructions tell you to run alongside the dependency install. That script is literally the two git commands joined:

npm install && npm run theme

Because the theme is external, a broken site is often a submodule problem rather than a Hugo problem. There is a .gitmodules file at the root, and the theme version is therefore not part of the main project's history. If a page renders unstyled, checking that themes/ is populated is the first move, not rewriting templates.

npm scripts wrap Hugo, and the preview server binds to a fixed port

The build chain has almost no custom logic. package.json names the project eksworkshop at version 1.0.0 and lists a set of scripts that call Hugo with a handful of flags. The preview script is the one most contributors live in:

npm run server

Underneath it runs Hugo in server mode with watch enabled, verbose output, Git info enabled, a bind address of 0.0.0.0 and a port fixed at 8080, with navigation to changed pages turned on. Because the port is pinned in the script rather than left to Hugo's default, two working copies on one machine will collide, and you override it by editing the script or by running Hugo yourself.

A second script, npm run drafts, adds the draft flag so pages that are stubs show up in the preview. It also disables fast render, which matters because a workshop chapter often links to pages that do not exist yet, and fast render would abort on them.

The Gitpod path takes a different route and runs hugo server directly with no port argument, which is why the Gitpod dialog you see mentions port 1313 while the local Mac and Linux instructions point at http://localhost:8080/. Two different preview ports depending on how you started the environment is a small trap worth knowing before you file a bug that turns out to be a port mismatch.

Link checking runs inside a Docker container, not on your machine

The test script is the most distinctive part of the build, and the least obvious. npm run test does not run a test framework. It starts a container, mounts the built output directory into it, and runs an HTML proofer over it:

npm run test

The proofer invocation carries several arguments that shape what counts as a failure. It ignores empty alt attributes, allows hash-only hrefs, and ignores URLs under a specific S3 path for templates. It also sets a User-Agent header and an Authorization token from the GITHUB_TOKEN environment variable, which is how it gets past rate limiting or private resources when checking external links. Timeouts are given explicitly for both connection and overall request, so a slow external host produces a failure rather than a hang.

Two consequences follow. The script requires Docker, so contributors on a machine without a container runtime cannot run it locally at all, and it depends on GITHUB_TOKEN being present in the environment when external links are checked. The build script, npm run build, simply runs Hugo and outputs to the public/ directory, which is what the test then reads.

Deployments sync to S3 and each branch gets its own route

Publishing is a set of aws s3 sync commands rather than a continuous delivery platform. The deploy script copies the built public/ directory to the bucket and deletes anything that is no longer in the build, so the bucket always mirrors the local output exactly:

aws s3 sync public/ s3://us-east-1-eksworkshop.com/ --delete

The remaining scripts split that behaviour by asset type. One syncs only HTML and XML with a short cache lifetime for content pages, another pushes templates/ to a template bucket under a path built from the AWS_BRANCH variable, and a third handles the remaining assets with a long cache lifetime. Splitting content from static assets is what allows the HTML to be revalidated often while images and downloads stay cached for a day.

The branch behaviour is documented at the top of the README. Commits to main build and deploy within a couple of minutes, and a commit to any other branch deploys to a custom route named after that branch. The example given is a branch called jenkinsworld, which would appear at a matching path under the site domain. The deployed commit hash is shown at the bottom of the menu panel, so a reviewer can confirm which revision the live site is serving.

The repository is in maintenance mode, and that changes what a contribution can be

The most important line in the README is the warning at the top. This repository is in maintenance mode and is currently only accepting bug fixes, and pull requests for new content should be adapted for the new EKS Workshop, which lives in a separate eks-workshop-v2 repository. The last push to this repository was on 2026-10-04, and the repository is not archived, so it still receives corrections, but new chapters are explicitly not wanted here.

That is a real constraint for anyone planning a workshop series. The older labs describe EKS as it was, and the newer chapters are being written elsewhere, which means a self-contained curriculum built on this repository will eventually need its chapters rewritten against the v2 content. Contributors should read the warning before doing any other setup work.

There is a smaller inconsistency worth knowing as well. The licence recorded for the repository is MIT-0, while package.json declares the ISC licence for the npm package named eksworkshop. Both are permissive, and MIT-0 drops even the notice-retention requirement, so the practical effect is limited, but a site that copies text from the workshops should record which licence it is working under rather than assuming the two files agree.

Where the workshop content actually lives

Content is organised as chapters in a content/ directory, and a contributor editing through the Gitpod browser opens a path of the form content/chapter/filename.md. The page is then previewed locally, committed, pushed, and turned into a pull request against the upstream main branch, after which the preview site refreshes.

The repository root shows the full shape of a site project rather than an application. There are archetypes/ for new content scaffolding, layouts/ and templates/ for Hugo rendering, static/ for assets, a config.toml for site configuration, an amplify.yml with a companion amplify.yml.readme, a codebuild-deploy.sh script, and a buildspec.yml.disabled file whose name says plainly that the build spec is not in active use. The .gitpod.yml at the root is what makes the Gitpod flow a one-command start, and CODE_OF_CONDUCT.md and CONTRIBUTING.md sit alongside it.

The practical takeaway for someone evaluating this project is that it is a publishing pipeline with a fixed set of conventions rather than a reusable toolkit. The scripts, the S3 layout, the branch routing and the submodule theme all work together, and adapting them to a different site means untangling that bundle first.

Editorial conclusion

Adopt this repository if you want to read and run the existing EKS labs or to send a bug fix against content that is already published. Do not plan new workshop chapters on it, because the maintainers ask that new content be adapted for the EKS Workshop v2 repository instead. Before you start, check the maintenance notice at the top of the README, verify that the theme submodule initialises on your machine, and confirm that Docker is available if you intend to run the link checker in npm run test.

Frequently asked questions

Official sources

1. aws-samples/eks-workshop on GitHub
2. Issues
3. License: MIT-0
4. Project website
5. README