hugo-cdn

A Hugo template that turns a content tree into a static CDN catalog: every collection and asset gets a JSON descriptor alongside the HTML page, plus a root manifest and a .well-known entry-point. Deployable to GitHub Pages or Netlify with no extra service.

The template does not host large binaries itself — it's a catalog. Each asset's href front-matter field points at where the bytes actually live (R2, S3, CloudFront, the same Pages site, anywhere). It is emitted as "url" in the JSON descriptors so consumers see a natural name.

What it produces

Path	Purpose
/index.json	Root catalog — list of collections, spec/version, links
/<collection>/index.json	Collection manifest — list of assets
/<collection>/<asset>/index.json	Per-asset descriptor (version, sha256, size, mime, url, tags…)
/.well-known/cdn.json	Stable entry-point pointing at /index.json
/sitemap.xml, /index.xml	Hugo-generated sitemap and RSS feed

Consumers (public/private front- or back-ends) can hit /.well-known/cdn.json once and crawl from there.

Layout

content/
  _index.md                    # catalog metadata
  releases/
    _index.md                  # collection metadata
    example-0.1.0/
      index.md                 # asset front-matter + notes
      (any bundled files…)     # exposed as `resources` in JSON

Adding an asset

hugo new --kind asset releases/my-asset-1.2.0/index.md

Then edit the front matter (version, href, mime, size, sha256, license, tags).

Local dev

hugo server
# http://localhost:1313/
# http://localhost:1313/index.json
# http://localhost:1313/.well-known/cdn.json

Deploy — GitHub Pages

1. Push to GitHub.
2. Settings → Pages → Source: GitHub Actions.
3. The workflow at .github/workflows/gh-pages.yml builds and deploys on push to main. baseURL is injected automatically.

Deploy — Netlify

1. New site from Git, point at the repo.
2. netlify.toml configures build, Hugo version, JSON CORS + cache headers, and .well-known headers. No further setup.

Customising the descriptor schema

The JSON shape is defined in three small templates:

• layouts/index.json — root catalog
• layouts/_default/list.json — collection manifest
• layouts/_default/single.json — per-asset descriptor

Add fields by editing those templates and the matching front matter.