Hugo Blog Workspaces

Hugo Blog Workspaces

Hugo blogs should be integrated as first-class Qloud website workspaces, not as a separate CMS or as local-only site checkouts.

Contract

  • Hugo remains the render authority.
  • Markdown, front matter, and structured files remain the source of truth.
  • Datacentre/control-plane owns identity, workspace provisioning, domains, certificates, production deploys, and app discovery.
  • generator owns shared rendering, editor UI, content schemas, and blog archetype behavior.
  • Nextcloud/Qloud is the shell and discovery layer. It should link users into the draft host and workspace tools, not become the canonical blog content store.
  • Postiz, ListMonk, Matomo, and similar services consume blog metadata or published feeds. They should not become the source of truth for posts.

Provisioning Shape

A managed blog should be provisioned through the same control-plane workspace path used by other websites:

  • Forgejo repository: canonical authored source
  • draft host: <slug>.drafts.quantalumin.com
  • production host: <slug>.sites.quantalumin.com
  • optional custom domain: for example henrysheehy.com
  • Qloud entrypoint: edit draft, preview, publish, open repo, view live site
  • production delivery: workspace commit -> Forgejo -> runner -> production site

The production host and any custom domains are deployment targets. The draft host is the primary hosted editing surface because the generator editor can use the workspace provider backed by generator-api.

Site Config

Use the shared archetype contract instead of a site-local layout fork:

[params.site]
archetype = "blog"

Hosted editing should continue to use params.qlMarkdownEditor workspace configuration emitted by the workspace/control-plane path. Blog repos should not hardcode live tokens or service credentials.

Content Model

The default blog content model should stay file-backed and schema-driven:

  • posts
  • series
  • notes
  • links
  • pages

Those are collection names for the future CMS/editor surface, not database tables. Creating, renaming, saving, publishing, or deleting a post should resolve to normal repository changes.

Integrations

  • Newsletter signup uses the shared ListMonk newsletter surface and brand-aware routing where available.
  • Postiz can syndicate published posts from Hugo front matter, RSS, or JSON Feed metadata.
  • Matomo should be attached through the control-plane site provisioning path.
  • RSS remains the baseline public feed; JSON Feed and ActivityPub can be layered on later without changing the authoring source of truth.

Non-Goals

  • Do not add a database-backed blog CMS.
  • Do not make Nextcloud files the canonical source of published posts.
  • Do not fork layouts in individual blog repos for shared behavior.
  • Do not make Postiz or ListMonk own the article body.