Current Behavior
Currently, local development for layer5io/layer5-academy relies on a globally installed Hugo binary or uses inconsistent invocations. This can lead to version mismatch issues between contributors' local environments and CI environments, causing build failures or discrepancies. Additionally, some documentation might reference outdated Makefile targets.
Desired Behavior
A contained, highly reproducible local development environment where dependencies are strictly managed. Just like the main Meshery documentation and other extension academies, running make setup should fetch the correct hugo-extended NPM dependency. Subsequent commands (make site, make build, etc.) should automatically route to this local binary, eliminating the need for a global Hugo installation.
Implementation
This approach ports over the standardized build processes established in other repositories (like meshery, exoscale-academy, and digitalocean-academy) to the main layer5-academy repository.
Specific changes should include:
- Makefile: Add a
check-deps target to validate npm and the local hugo binary before execution. Reroute build, site, serve, clean, and theme-update to trigger 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, stripping out unnecessary global dependencies.
- Documentation: Update
README.md and CONTRIBUTING.md to remove references to outdated targets and emphasize the make setup -> make site workflow.
Acceptance Tests
Contributor Guides and Resources
Current Behavior
Currently, local development for
layer5io/layer5-academyrelies on a globally installed Hugo binary or uses inconsistent invocations. This can lead to version mismatch issues between contributors' local environments and CI environments, causing build failures or discrepancies. Additionally, some documentation might reference outdated Makefile targets.Desired Behavior
A contained, highly reproducible local development environment where dependencies are strictly managed. Just like the main Meshery documentation and other extension academies, running
make setupshould fetch the correcthugo-extendedNPM dependency. Subsequent commands (make site,make build, etc.) should automatically route to this local binary, eliminating the need for a global Hugo installation.Implementation
This approach ports over the standardized build processes established in other repositories (like
meshery,exoscale-academy, anddigitalocean-academy) to the mainlayer5-academyrepository.Specific changes should include:
check-depstarget to validatenpmand the localhugobinary before execution. Reroutebuild,site,serve,clean, andtheme-updateto triggernpm runscripts.dev:*scripts (e.g.,dev:build,dev:clean,dev:site) to explicitly handle Hugo commands with the correct flags, stripping out unnecessary global dependencies.README.mdandCONTRIBUTING.mdto remove references to outdated targets and emphasize themake setup->make siteworkflow.Acceptance Tests
make setupinstalls the localhugo-extendeddependency cleanly.make sitesuccessfully spins up the local development server using the NPM-managed binary.make cleancorrectly wipes the build cache.Contributor Guides and Resources