Skip to content

Generate WebP for static Markdown images - #1379

Open
Dev-chxrlez wants to merge 1 commit into
layer5io:masterfrom
Dev-chxrlez:fix/static-image-webp
Open

Dev-chxrlez wants to merge 1 commit into
layer5io:masterfrom
Dev-chxrlez:fix/static-image-webp

Conversation

@Dev-chxrlez

@Dev-chxrlez Dev-chxrlez commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Mount the static directory as a Hugo asset source so the Markdown image hook can generate WebP versions of root-relative PNG and JPEG links.
  • Keep the existing static mount so the original URLs continue to serve the fallback files.

Verification

  • Built a focused fixture with Hugo Extended 0.158.0. The build generated WebP for a static PNG and JPEG and published both originals at their original paths. It also generated WebP for an existing page-bundle image and rendered external images and SVGs through the existing fallback.
  • The full local site build is pending because the environment lacks Go for Hugo module resolution.

Resolves #1284

Summary by CodeRabbit

  • Bug Fixes
    • Images referenced by absolute paths can now be found in static files when they aren’t available through other image lookups. Static images are also included in the site’s asset mapping, making them available to pages.

Resolves layer5io#1284

Signed-off-by: Charles Guarino <charleseffectsyt@gmail.com>
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

Hugo now mounts files from static under assets/staticimg. When earlier image lookups fail for a destination that begins with /, the image render template also checks staticimg.

Changes: Static image lookup

Layer / File(s) Summary
Mount and resolve static images
hugo.toml, layouts/_default/_markup/render-image.html
Hugo mounts static under assets/staticimg. The image render template checks staticimg for unresolved destinations that begin with /. Its comment now describes content and static files as mounted under assets.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Possibly related PRs

  • layer5io/docs#1274: Both PRs change the Markdown image rendering hook and affect the WebP processing path.

Suggested reviewers: hiyach28, banana-three-join

Merge Risk: Low · up to 31481

Static images referenced by root-relative paths now get WebP alternatives, and the original URLs remain available. Page-relative references to static images would still get only the original image. Nothing in the current content appears to be affected, so the risk is low.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "Generate WebP for static Markdown images" matches the main change. The PR mounts static/ as an asset source and adds a fallback lookup in the Markdown image render hook, so Markdown referen…
Linked Issues check Passed [#1284] Requirement: PNG/JPEG images under static/, referenced from Markdown, are offered as WebP with the original as fallback, and no previously published image URL 404s. Evidence: hugo.toml (head) …
Out of Scope Changes check Passed All changed hunks serve the #1284 objective. hugo.toml adds one module mount for static to assets/staticimg, and the existing static mount is kept. render-image.html adds the staticimg fallback lookup…
Full details: Title check

Explanation

The title "Generate WebP for static Markdown images" matches the main change. The PR mounts static/ as an asset source and adds a fallback lookup in the Markdown image render hook, so Markdown references to static PNG and JPEG images produce WebP versions. The original files stay published at their existing paths. The title is short, specific, and names the primary behavior from the developer's perspective.

Full details: Linked Issues check

Explanation

[#1284] Requirement: PNG/JPEG images under static/, referenced from Markdown, are offered as WebP with the original as fallback, and no previously published image URL 404s. Evidence: hugo.toml (head) adds a module mount source="static" target="assets/staticimg", so static files become Hugo resources. In layouts/_default/_markup/render-image.html, when the earlier lookups fail and the destination begins with "/", the hook resolves the image via resources.Get(path.Join "staticimg" $rel). When a resource is found, the hook emits a <picture> with a WebP <source> from .Process "webp q85" and keeps the original $dest as the <img> src, which is the fallback. The existing static mount to target "static" is retained in hugo.toml, so original paths keep serving. External, scheme-bearing, and SVG references skip the lookup and render as before. The comment update in the template matches the new mount. Not verified: the full site build, which the PR states is pending. The author's fixture result is not independently rerun here. Limitation: the new lookup applies only to root-relative destinations. Relative references from content to static files are not covered, which the issue does not clearly require.

Full details: Out of Scope Changes check

Explanation

All changed hunks serve the #1284 objective. hugo.toml adds one module mount for static to assets/staticimg, and the existing static mount is kept. render-image.html adds the staticimg fallback lookup, limited to root-relative PNG/JPEG destinations. The comment edit in render-image.html documents the new mount and is part of the same change. No unrelated files or behavior changes appear in the whole-PR diff from merge base d058ff0 to head 314818d.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional comments: 1

layouts/_default/_markup/render-image.html-29-29: 1

29-29: Minor · Functional Correctness · Heavy lift

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Resolve relative references to static images too.

For a page at /guide/, ![diagram](diagram.png) can refer to static/guide/diagram.png. The root-relative guard skips the new lookup, so the hook emits only the original image. The linked issue covers Markdown references to static PNG and JPEG images, not only root-relative references. Resolve relative URLs against the page URL before looking up the static resource.

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: caa7d2c8-4068-4de4-9b82-dbc6c2782670
Commits

Reviewing files that changed from the base of the PR and between d058ff0 and 314818d.

Files selected for processing: 2

  • hugo.toml
  • layouts/_default/_markup/render-image.html

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

@miacycle miacycle left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, tightly scoped change, and the approach is sound: mounting static a second time under assets/staticimg keeps the original URLs serving while giving the render hook a resource to process, so no content edits are needed.

Two things I liked:

  • The new fallback is guarded to root-relative destinations only (hasPrefix $dest "/"), which matches exactly the paths the static mount can resolve.
  • The original static mount is untouched, so the <img> fallback still points at a real file if WebP processing ever misses.

One non-blocking question: the PR notes the full local site build is still pending because the environment lacks Go for Hugo module resolution. Does the CI build for this repo exercise the new mount (in other words, would a broken mount fail CI), or is there a fixture from your verification worth keeping as a regression check? If CI covers it, this is good to go from my side.

@Dev-chxrlez

Dev-chxrlez commented Nov 16, 2026 via email

Copy link
Copy Markdown
Contributor Author

@suttonskate

Copy link
Copy Markdown
Member

This is a good item to add to the weekly Websites meeting agenda. You can add this item in the doc, attend, and present it. Meeting details can be found at https://meshery.io/calendar.

@simihablo simihablo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @Dev-chxrlez 😄

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Preview deployment: https://docs.layer5.io/pr-preview/pr-1379/

Note: Preview may take a moment (GitHub Pages deployment in progress). Please wait and refresh. Track deployment here

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Process static/ images through the WebP pipeline

4 participants