[Hugo] Phase 1 · Decision: images layout (page bundles, a shared folder, or hybrid) #8308

Parent: #8297 · Open decision: "Images layout"

Facts

• About 11,200 images: 9,265 SVG, 1,315 WebP, about 600 PNG/JPG/GIF. src/ is 360 MB and static/ is 157 MB.
• The converter copies 9,431 assets that sit next to collection documents, so most collection images are already bundle-local.
• 40 front-matter images point outside the bundle (../, src/assets/…): blog 9, resources 27, news 4.
• Layouts and sections import shared images from src/assets/images (logos, illustrations, icons).
• Hugo only processes raster images. SVGs are copied as-is, so resizing work applies to about 1,900 files.
• Blog posts carry thumbnail and darkthumbnail (267 uses), plus thumbnail_svg/darkthumbnail_svg.

Recommendation: hybrid

• Page bundles for anything owned by one document (what the converter already does).
• hugo/assets/images/ (processed with resources.Get) for shared images used by layouts, with the same sub-paths as src/assets/images so ports are mechanical.
• hugo/static/ for files that must keep an exact URL (static/brand, static/press, static/fonts, llms.txt, CNAME-adjacent files).
• Fix the 40 out-of-bundle references by copying the file into the bundle (converter rule) rather than pointing at shared paths.

Tasks

• Maintainers confirm.
• Converter: copy out-of-bundle front-matter images into the bundle and rewrite the path (clears the 40 warnings).
• Document the rule in CHEATSHEET.md.

Contributor Resources and Handbook

The layer5.io website uses Gatsby, React, and GitHub Pages. Site content is found under the master branch.

• 📚 See contributing instructions.
• 🎨 Wireframes and designs for Layer5 site in Figma (open invite)
• 🙋🏾🙋🏼 Questions: Discussion Forum and Community Slack.

Join the Layer5 Community by submitting your community member form.