Current Behavior

Currently, local theme development and testing for layer5io/academy-theme relies on a globally installed Hugo binary or uses inconsistent invocations. This can lead to version mismatch issues between contributors' local environments and CI, causing build failures, discrepancies, or friction for newcomers trying to preview theme changes locally.

Desired Behavior

A contained, highly reproducible local development environment where dependencies are strictly managed via npm. Running make setup should fetch the correct hugo-extended NPM dependency. Subsequent commands (e.g., make site, make build) should automatically route to this local binary, eliminating the need for a global Hugo installation for theme contributors.

Implementation

This approach standardizes the local build process for the theme, ensuring it stays synchronized with the CI hygiene recently established in the content repositories (like meshery/meshery, digitalocean-academy, exoscale-academy, and academy-example).

Specific changes should include:

• Makefile: Add a check-deps target to validate npm and the local hugo binary before execution. Reroute existing test site and build targets to trigger their respective npm run scripts.
• package.json: Add dev:* scripts (e.g., dev:build, dev:clean, dev:site) to explicitly handle Hugo commands with the correct flags, relying on the local node module instead of a global installation.
• Documentation: Update README.md and CONTRIBUTING.md to remove references to installing Hugo globally, emphasizing the unified make setup -> make site workflow.

Acceptance Tests

• make setup installs the local hugo-extended dependency cleanly.
• make site successfully spins up the local test server using the NPM-managed binary.
• make clean correctly wipes the build cache using the local binary.
• A contributor without a globally installed Hugo can build and preview the theme from a fresh clone.

Contributor Guide and Resources

• 📚 Instructions for contributing to academy-theme
• academy-example documentation site and source
• 🎨 Wireframes and designs for Layer5 site in Figma (open invite)
• 🙋🏾🙋🏼 Questions: Layer5 Discussion Forum and Layer5 Community Slack