improove modularity of frenet site theme

[gogo2464]

I would like to reuse https://github.com/freenet/web/tree/main/hugo-site/themes/freenet .

but I can not do hugo mod init https://github.com/freenet/web/tree/main/hugo-site/themes/freenet in a single line. Could we split the repo with a clonable theme with command hugo mod init https://github.com/freenet/web/ please?

[sanity]

Issue Priority Assessment

Generated: 2026-02-18T22:11:42.558417590+00:00
Issue hash: ef21952b

Value Assessment

There is a modest but real user impact here for people trying to reuse the Freenet Hugo theme as a standalone module: the theme lives inside hugo-site/themes/freenet alongside the full site, so the hugo mod init https://github.com/freenet/web/tree/main/hugo-site/themes/freenet command fails because Hugo modules expect a repository root rather than a nested subdirectory. Anyone who wants to adopt just the look-and-feel for a fork, mirror, or related site therefore has to clone the entire freenet/web tree and manually extract the theme, which adds friction and invites duplication. The severity is low–it doesn’t break the existing site–but it does make theme reuse harder for community members or downstream projects whose primary goal is to share the theme rather than the whole website.

Strategically, the Freenet website’s objectives center on maintainability and the reuse of tooling (the layout and Ghost Key integration being common elements). Making the theme easily importable as a Hugo module would reinforce that strategy by letting other repositories import it via module semantics instead of copying files. Because the Hugo site already references its theme through hugo-site/config.toml and keeps the theme content in one place, splitting the theme into its own repository or at least making the repo root align with Hugo module expectations would keep the main site focused on content while supporting downstream contributors who want to build on the same visual system.

This request isn’t blocking any critical path work—core functionality like Ghost Key WASM builds (rust/gkwasm), the Axum API, or Hugo content updates can continue while the theme remains nested. No other open major contributions appear to be waiting on this modularization, so it doesn’t hold up releases or infrastructure changes. That said, future contributions that rely on the theme as a dependency would benefit, so clearing this hurdle sooner keeps those workflows unblocked.

There’s no urgent timing pressure mentioned, and nothing in the codebase indicates a security or stability risk tied to the current setup. Addressing it is nice-to-have structural cleanup; keeping it in the backlog with a “help wanted” tag is likely sufficient unless someone actively needs to consume the theme as a Hugo module.

Cost Assessment

Splitting the theme out so that someone can run hugo mod init https://github.com/freenet/web/ would touch nearly the entire Hugo surface area. The theme itself lives under hugo-site/themes/freenet, so every layouts, shortcodes, assets, and static file under that directory would need to be packaged for independent reuse, and the site’s config.toml would need a new module declaration plus retained mounts for static/wasm so the Ghost Key tooling still finds hugo-site/static/wasm. Because all of the “build the site” commands in Makefile.toml just cd into hugo-site and run hugo, any repo restructuring that changes where the theme sits in relation to the site root would also require touching those tasks (and likely the README and developer scripts) so the tooling still knows where to place the generated CSS/JS and wasm output.

The technical complexity comes from the amount of implicit coupling between the theme and the rest of the site. themes/freenet/layouts/partials/head/css.html invokes Hugo resources on assets/css/freenet.css, and head/js.html pulls in /js/nacl.min.js, /js/cbor.min.js, etc., which currently live under hugo-site/static/js. Likewise the menu partial references /freenet_logo.svg in the site static tree, and the api-url, stripe-donation-form, and river-invite-button shortcodes rely on window.ghostkeyApiUrl being injected by the theme’s api-url.html. Any move to make the theme “clonable” would have to decide whether those supporting scripts, logos, and API helper partials accompany the theme copy or remain part of the main site; separating them cleanly while preserving the theme’s current behavior is nontrivial and propagates changes across static assets, layout partials, and shortcode logic.

There’s also a real risk that reshuffling directories breaks the existing CI/CD pipeline. The cargo make build-site / build-hugo-release tasks rebuild wasm via rust/gkwasm into hugo-site/static/wasm before running Hugo, so if the theme is moved or modularized incorrectly, those builds might no longer find the wasm output or the theme’s static dependencies (fonts, logos, crypto libs). Changing the repo layout without updating every reference to /css/, /js/, /wasm/, and /freenet_logo.svg in both the theme and the site would likely lead to broken Ghost Key pages, missing assets, and failing GitHub Actions that expect the current structure.

Testing the change thoroughly would therefore be fairly heavy: you would need to rebuild the wasm assets and run cargo make build-site and cargo make build-hugo-release locally (or in CI) to prove everything still compiles, plus spin up hugo server to manually check that the navigation partials, Stripe donation shortcode, and Ghost Key shortcodes still render with the correct API endpoints and static files. On top of that, you’d want to verify that a consumer can now run hugo mod init https://github.com/freenet/web/ as advertised and that the theme still resolves its CSS/JS and /freenet_logo.svg assets in that modular context, since the whole change is motivated by reusability.

---

Generated by issue-prioritizer