chore: refine shared build targets and npm scripts across docs and academy repos - #174
Conversation
Signed-off-by: Lenox Wiltshire <lenoxwiltshire@gmail.com>
📝 WalkthroughWalkthroughThe change updates package scripts, Makefile targets, and README instructions for Node.js-based builds, serving, linting, link checking, production ChangesDevelopment workflow
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
📖 Pull request preview: https://layer5io.github.io/academy-example/pr-preview/pr-174/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@package.json`:
- Around line 19-31: Update the _check:links script in package.json to execute
the advertised htmltest command using HTMLTEST_VERSION instead of echoing a
skipped message. Preserve the existing check:links, test, postbuild:preview, and
postbuild:production script wiring so these flows perform real link validation.
In `@README.md`:
- Around line 204-205: Update the README instructions for updating the
academy-theme package by replacing the unavailable make theme-update command
with the supported npm run theme:update command, or remove the instruction if no
supported update workflow exists.
- Around line 132-150: Update the Page Bundling example so hugo-logo.png is
placed in the same leaf bundle directory as lesson-1.md, and show lesson-1.md
alongside the image in the directory tree. Keep the existing relative Markdown
reference unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: d9ad9d2e-fe19-4919-ada9-a7a7ecf4ef96
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (3)
MakefileREADME.mdpackage.json
| "_check:links": "echo \"Skipped: go run github.com/wjdp/htmltest@${HTMLTEST_VERSION:-v0.17.0} -s\"", | ||
| "build": "npm run _build", | ||
| "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", | ||
| "build:production": "npm run _hugo -- --minify --gc", | ||
| "build:preview": "npm run _hugo-dev -- --cleanDestinationDir --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", | ||
| "build:production": "npm run _hugo -- --cleanDestinationDir --minify --gc", | ||
| "site": "npm run _site", | ||
| "site:no-watch": "npm run _hugo-dev -- --minify --watch=false server", | ||
| "serve": "npm run _serve", | ||
| "clean": "rm -Rf public/* resources", | ||
| "make:public": "git init -b main public", | ||
| "check:links": "npm run _check:links", | ||
| "precheck:links": "npm run build", | ||
| "postbuild:preview": "npm run _check:links", | ||
| "postbuild:production": "npm run _check:links", | ||
| "test": "npm run check:links", |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Run the link checker instead of returning success from a no-op.
_check:links only prints Skipped and exits with status 0. The check:links, test, postbuild:preview, and postbuild:production scripts therefore never validate links. This creates false-green builds while the Makefile and README advertise link checking.
Replace the echo with the command shown below. If link checking is intentionally disabled, remove the successful check path and update the documentation.
Proposed fix
- "_check:links": "echo \"Skipped: go run github.com/wjdp/htmltest@${HTMLTEST_VERSION:-v0.17.0} -s\"",
+ "_check:links": "go run github.com/wjdp/htmltest@${HTMLTEST_VERSION:-v0.17.0} -s",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "_check:links": "echo \"Skipped: go run github.com/wjdp/htmltest@${HTMLTEST_VERSION:-v0.17.0} -s\"", | |
| "build": "npm run _build", | |
| "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", | |
| "build:production": "npm run _hugo -- --minify --gc", | |
| "build:preview": "npm run _hugo-dev -- --cleanDestinationDir --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", | |
| "build:production": "npm run _hugo -- --cleanDestinationDir --minify --gc", | |
| "site": "npm run _site", | |
| "site:no-watch": "npm run _hugo-dev -- --minify --watch=false server", | |
| "serve": "npm run _serve", | |
| "clean": "rm -Rf public/* resources", | |
| "make:public": "git init -b main public", | |
| "check:links": "npm run _check:links", | |
| "precheck:links": "npm run build", | |
| "postbuild:preview": "npm run _check:links", | |
| "postbuild:production": "npm run _check:links", | |
| "test": "npm run check:links", | |
| "_check:links": "go run github.com/wjdp/htmltest@${HTMLTEST_VERSION:-v0.17.0} -s", | |
| "build": "npm run _build", | |
| "build:preview": "npm run _hugo-dev -- --cleanDestinationDir --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", | |
| "build:production": "npm run _hugo -- --cleanDestinationDir --minify --gc", | |
| "site": "npm run _site", | |
| "serve": "npm run _serve", | |
| "clean": "rm -Rf public/* resources", | |
| "make:public": "git init -b main public", | |
| "check:links": "npm run _check:links", | |
| "precheck:links": "npm run build", | |
| "postbuild:preview": "npm run _check:links", | |
| "postbuild:production": "npm run _check:links", | |
| "test": "npm run check:links", |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@package.json` around lines 19 - 31, Update the _check:links script in
package.json to execute the advertised htmltest command using HTMLTEST_VERSION
instead of echoing a skipped message. Preserve the existing check:links, test,
postbuild:preview, and postbuild:production script wiring so these flows perform
real link validation.
| Enhance your course with images and other visual aids using the **Page Bundling** method, which keeps assets alongside the content that references them and ensures they resolve correctly for each organization. | ||
|
|
||
| **How to Add an Image** | ||
|
|
||
| 1. Place your image file (e.g., `hugo-logo.png`) in your scoped static directory: | ||
| 1. Place your image file directly in the same directory as your Markdown content: | ||
|
|
||
| ```text | ||
| static/<your-organization-uid>/images/hugo-logo.png | ||
| ``` | ||
| 2. In your `lesson-1.md` file, embed the image using the `usestatic` shortcode. The `path` is relative to your scoped static folder: | ||
| ```text | ||
| content/learning-paths/<your-organization-uid>/ | ||
| └── <your-course>/ | ||
| └── <your-module>/ | ||
| ├── _index.md | ||
| └── hugo-logo.png | ||
| ``` | ||
|
|
||
| ```text | ||
| ![The Hugo Logo]({{</* usestatic path="images/hugo-logo.png" */>}}) | ||
| ``` | ||
| 2. In your `lesson-1.md` file, reference the image using standard Markdown syntax: | ||
|
|
||
| ```markdown | ||
|  | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n --hidden \
--glob '!node_modules/**' \
--glob '!public/**' \
'render-image\.html|PageInner\.Parent|Parent\.Resources|Resources\.Get' .Repository: layer5io/academy-example
Length of output: 162
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf 'Tracked files relevant to README/theme/config:\n'
git ls-files | rg '(^README\.md$|^config|academy-theme|themes|layouts|content|assets)$|(^themes/academy-theme|academy-theme|layouts/|content/)' | head -200
printf '\nREADME relevant section:\n'
sed -n '120,160p' README.md
printf '\nSearch for page-bundle, Parent, Resources, render hooks, and resources in repository:\n'
rg -n --hidden --glob '!node_modules/**' --glob '!public/**' 'page[- ]?bundle|PageInner\.Parent|\.Parent|Parent\.(Resources|Params)|Resources\.(GetMatch|Get|Params|Resources)|render[-_].*html|resources' . | head -300Repository: layer5io/academy-example
Length of output: 15035
🌐 Web query:
Hugo render hooks page resources bundle context Resources.GetMatch parent resources
💡 Result:
To access page resources within a Hugo render hook, you use the.Page object available in the render hook context to call resource methods like.Resources.GetMatch [1][2][3]. Key considerations for accessing these resources include: 1. Accessing Page Resources: Inside a render hook, the.Page object represents the page currently being rendered [3]. You can access its bundled resources by calling.Page.Resources.GetMatch.Destination (or.Get) [4][5][2]. Note that.Destination contains the link or image path from the Markdown file [5][2]. 2. Bundle Context: Page resources are only available if the content file is part of a page bundle (a directory with an index.md or _index.md file) [1][6]. If the page is not a bundle, or if the resource is not correctly associated with that bundle, the lookup will fail [7][3]. 3. Branch Bundles: If you are working with a branch bundle (e.g., a sub-page within a section), you may need to access the parent page's resources if the current page itself is not a bundle or does not contain the target resource [7]. In such cases, you can use.Page.Parent.Resources.GetMatch [7]. 4. Fallback Strategy: Because render hooks are applied globally to images or links, it is a common best practice to implement a fallback mechanism [5][3]. You can attempt to find the resource in the page bundle first, and if not found, fall back to global assets using the resources.Get function [5]. Example implementation pattern: {{ $r:=.Page.Resources.GetMatch.Destination }} {{ if not $r }} {{ $r = resources.Get.Destination }} {{ end }} {{ with $r }} <img src="{{.RelPermalink }}"...> {{ end }} This ensures your render hook gracefully handles both page-local resources and global assets [5].
Citations:
- 1: https://gohugo.io/content-management/page-resources/
- 2: https://discourse.gohugo.io/t/render-image-hook-and-leaf-bundles/35896
- 3: https://discourse.gohugo.io/t/leaf-bundle-resources-in-templates/36458
- 4: https://discourse.gohugo.io/t/image-render-hook-has-no-access-to-page-resources/39498
- 5: https://discourse.gohugo.io/t/get-resource-from-page-bundle-or-the-assets-dir/36340
- 6: https://www.hugodoc.com/content-management/page-resources/
- 7: https://discourse.gohugo.io/t/how-to-access-resources-from-pages-within-a-branch-bundle/28772
🌐 Web query:
Hugo image render hook markdown image syntax Resources.GetMatch relative to markdown page
💡 Result:
In Hugo, image render hooks use the .Page context to resolve resources. To resolve an image relative to the current Markdown page (typically a leaf bundle), you use the .Page.Resources.GetMatch method within your render-image.html hook [1][2]. Key considerations for implementation: 1. Context: Use .Page to access the page-level resources [1]. Inside a render hook, the .Destination variable contains the image URL provided in your Markdown [1][3]. 2. Resolution Strategy: Because Markdown image links are treated as destinations, they are not automatically resolved to page resources by default in the same way ref or relref work unless you use a render hook [1][4]. A robust implementation typically checks for the resource in the current page bundle first, and often falls back to the global assets directory [3]: {{ $destination:=.Destination }} {{ $image:=.Page.Resources.GetMatch $destination }} {{ if not $image }} {{ $image = resources.Get $destination }} {{ end }} {{ with $image }} {{ else }}
{{ end }} 3. Pathing: Ensure your Markdown image syntax uses a path relative to the page bundle (e.g.,
 or , not an absolute path starting with /) [5][6]. If you use a leading slash, Hugo may attempt to resolve the image from the root of the site, causing GetMatch to fail because it is scoped to the page bundle [6]. 4. Advanced Note: If you are using components or nested structures where content might be included (e.g., via RenderShortcodes), you may consider using .PageInner instead of .Page to ensure the context remains consistent with the file currently being rendered [1]. Always wrap your resource access in with or if statements to handle cases where the file cannot be found, preventing your build from failing with a nil pointer error [3][6].
Citations:
- 1: https://gohugo.io/render-hooks/images/
- 2: https://discourse.gohugo.io/t/render-image-hook-and-leaf-bundles/35896
- 3: https://discourse.gohugo.io/t/get-resource-from-page-bundle-or-the-assets-dir/36340
- 4: https://discourse.gohugo.io/t/images-relative-to-a-page-bundle/46957
- 5: https://discourse.gohugo.io/t/image-render-hook-has-no-access-to-page-resources/39498
- 6: https://discourse.gohugo.io/t/image-render-hook-error/37804
Use a leaf-bundle image path for the Page Bundling example.
The example puts hugo-logo.png in <your-module>/ but then has lesson-1.md reference it. Hugo resolves Markdown images relative to the Markdown page unless the image render hook specifically searches parent resources, so place the image in the referenced page’s bundle.
Proposed documentation fix
- └── <your-module>/
- ├── _index.md
- └── hugo-logo.png
+ └── <your-module>/
+ └── lesson-1/
+ ├── index.md
+ └── hugo-logo.png
-2. In your `lesson-1.md` file, reference the image using standard Markdown syntax:
+2. In `lesson-1/index.md`, reference the image using standard Markdown syntax:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Enhance your course with images and other visual aids using the **Page Bundling** method, which keeps assets alongside the content that references them and ensures they resolve correctly for each organization. | |
| **How to Add an Image** | |
| 1. Place your image file (e.g., `hugo-logo.png`) in your scoped static directory: | |
| 1. Place your image file directly in the same directory as your Markdown content: | |
| ```text | |
| static/<your-organization-uid>/images/hugo-logo.png | |
| ``` | |
| 2. In your `lesson-1.md` file, embed the image using the `usestatic` shortcode. The `path` is relative to your scoped static folder: | |
| ```text | |
| content/learning-paths/<your-organization-uid>/ | |
| └── <your-course>/ | |
| └── <your-module>/ | |
| ├── _index.md | |
| └── hugo-logo.png | |
| ``` | |
| ```text | |
| ![The Hugo Logo]({{</* usestatic path="images/hugo-logo.png" */>}}) | |
| ``` | |
| 2. In your `lesson-1.md` file, reference the image using standard Markdown syntax: | |
| ```markdown | |
|  | |
| ``` | |
| Enhance your course with images and other visual aids using the **Page Bundling** method, which keeps assets alongside the content that references them and ensures they resolve correctly for each organization. | |
| **How to Add an Image** | |
| 1. Place your image file directly in the same directory as your Markdown content: | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 132 - 150, Update the Page Bundling example so
hugo-logo.png is placed in the same leaf bundle directory as lesson-1.md, and
show lesson-1.md alongside the image in the directory tree. Keep the existing
relative Markdown reference unchanged.
| # Update the academy-theme package version | ||
| make theme-update |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Remove or implement the unavailable make theme-update command.
The Makefile states that this repository has no theme-update target. Its .PHONY list also omits that target. package.json defines theme:update, but that npm script does not create a Makefile target. Following this README command fails.
Remove these lines or document npm run theme:update instead.
Proposed documentation fix
-# Update the academy-theme package version
-make theme-update📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Update the academy-theme package version | |
| make theme-update |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 204 - 205, Update the README instructions for
updating the academy-theme package by replacing the unavailable make
theme-update command with the supported npm run theme:update command, or remove
the instruction if no supported update workflow exists.
2 participants
Propagates the latest round of cleanup and refinement to the shared Makefile and npm script standard.
The
site-no-watchtarget is nowserve, matching itssitecounterpart. Linting is split intolintandlint-fix, both running a pinnedmarkdownlint-cli2so local and CI runs agree; Prettier has been dropped, since its reachable surface here is a handful of root files and unconfigured it would reformat Go templates and content.build-productionacceptsBASE_URL, and--cleanDestinationDirnow applies only to the build scripts, so starting the dev server no longer wipespublic/.Also removed some dead weight:
rtlcss,npm-check-updatesinoptionalDependencies, and theHTMLTEST_VERSIONvariable, whose pinned default now lives with its consumer.The Makefile header documents the shared contract and which sections are repo-specific. Since this repo is the starter template every new academy is forked from, the README needed the most attention: command descriptions were corrected and the newer targets documented, Hugo was dropped from the prerequisites since it comes from
make setup, the directhugo serverinstructions were replaced withmake site, and the asset guidance now uses Page Bundling instead of the deprecatedusestaticshortcode.Signed commits
Summary by CodeRabbit
Documentation
Developer Experience
serve.