Current Behavior
Currently, local development for layer5io/docs relies on a globally installed Hugo binary. The Makefile directly invokes hugo for critical targets (e.g., build: hugo and site: check-go hugo server -D -F). This reliance on a global installation can lead to version mismatch issues between contributors' local environments and CI, causing build failures or discrepancies.
Desired Behavior
A contained, highly reproducible local development environment where dependencies are strictly managed. Just like the main meshery/meshery documentation and the academy repositories, running make setup should fetch the correct hugo-extended NPM dependency. Subsequent commands (make site, make build, make clean, 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 Layer5 repositories (like meshery, exoscale-academy, and meshery-academy) to the docs repository.
Specific changes should include:
- Makefile: Add a
check-deps target to validate npm and the local hugo binary before execution. Reroute existing targets (build, site, clean) 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, stripping out unnecessary global dependencies.
- Documentation: Update
README.md and CONTRIBUTING.md to remove any references to installing Hugo globally and emphasize the unified make setup -> make site workflow.
Acceptance Tests
Contributor Guide and Resources
Current Behavior
Currently, local development for
layer5io/docsrelies on a globally installed Hugo binary. TheMakefiledirectly invokeshugofor critical targets (e.g.,build: hugoandsite: check-go hugo server -D -F). This reliance on a global installation can lead to version mismatch issues between contributors' local environments and CI, causing build failures or discrepancies.Desired Behavior
A contained, highly reproducible local development environment where dependencies are strictly managed. Just like the main
meshery/mesherydocumentation and the academy repositories, runningmake setupshould fetch the correcthugo-extendedNPM dependency. Subsequent commands (make site,make build,make clean, 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 Layer5 repositories (like
meshery,exoscale-academy, andmeshery-academy) to thedocsrepository.Specific changes should include:
check-depstarget to validatenpmand the localhugobinary before execution. Reroute existing targets (build,site,clean) to trigger their respectivenpm 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 any references to installing Hugo globally and emphasize the unifiedmake 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 using the local binary.Contributor Guide and Resources