aureliasrs specifications
Orchestration specification

Staged Content Mounts

Repository documentation is staged from docs/ into .cache/docs-site/ and mounted into a Hugo site, so the docs stay where they are owned.

Applies at
.cache/docs-site/
Status
Stable

01 Defines

A two-step bridge between plain Markdown documentation and a Hugo site: a preparation script copies docs/ into a disposable staging directory with front matter added, and Hugo module mounts publish that directory beneath the site’s own content.

02 Applies when

  • Documentation written for the repository should also appear on a published site.
  • The source Markdown has no Hugo front matter and should not need any.
  • Site content and repository documentation must stay in separate trees.

03 Boundaries

  • The staged copy is never edited; changes are made in docs/.
  • Staging adds front matter only; it does not restructure, merge, or rewrite the documents.
  • README.md files and dot-prefixed entries are owner documentation for directories and are not staged.

Expected behaviour

  1. 01
    make prepare.hugo runs the configured HUGO_PREPARE_COMMAND before every check.hugo build.
  2. 02
    Each .md or .html file under docs/ is written to .cache/docs-site/content/ at the same relative path, with a title derived from its file name.
  3. 03
    Missing docs/ or an empty docs/ produces a skip: message and a successful exit.
  4. 04
    The staging directory is listed in HUGO_CLEAN_PATHS, so make clean removes it.
  5. 05
    Mounted documentation is published under its own section and never mixes with the site’s own content.

Behaviour#

Documentation under docs/ is written as ordinary Markdown for people reading the repository. A Hugo site wants front matter and a content tree. Rather than make the documents serve both masters, a small script stages a Hugo-ready copy and the site mounts it.

FlowFrom docs/ to a published page
  1. 01 Author Edit Markdown in docs/, where it is owned Owner Documentation
  2. 02 Stage prepare-site-content.mjs writes .cache/docs-site/content/<path> with front matter
  3. 03 Mount [module] mounts place the staged tree at content/repository
  4. 04 Build check.hugo renders it alongside the site’s own content Static Websites

The mount, not the script, decides where the pages appear. The script only knows about docs/ and .cache/; the site decides that repository documentation is published beneath /repository/ so it cannot collide with library pages.

What staging adds#

The script prepends a minimal front matter block — a title built from the file name with separators turned into spaces and words capitalised, a date, and draft: false — followed by the original content unchanged. A file at docs/build/local-development.md becomes .cache/docs-site/content/build/local-development.md with the title “Local Development”.

Live reload#

hugo serve does not run the staging step. Pages generated from docs/ are missing from a live-reload session until make prepare.hugo (or make check.hugo) has run once, and Hugo can report module mount errors if the staged directories are absent.

Examples#

The site mounts its own content first and the staged documentation beneath a dedicated section:

www/specifications/hugo.yaml 
module:
  mounts:
    - source: content
      target: content

    # Repository documentation under docs/ is staged by `make prepare.hugo` and
    # published beneath /repository/ so it never mixes with the library.
    - source: ../../.cache/docs-site/content
      target: content/repository

The repository wires the script and its clean-up path into the Hugo module:

scripts/build/repository.mk 
HUGO_PREPARE_COMMAND := node scripts/docs/prepare-site-content.mjs
HUGO_CLEAN_PATHS := .cache/docs-site

Connections

How Staged Content Mounts relates to the library

Staged Content Mounts and 2 related specificationsStatic WebsitesStatic WebsitesExplicit SkipsExplicit Skips
RefinesComposesRelies onFollowed byContrasts with

Composed into

Relies on