Scaffold the AgStack documentation site

Hugo + Docsy site that pulls component documentation out of other AgStack
repositories and publishes it as one set of docs. agstack/pancake is wired in
live as the single real import; its docs/ tree is, with palefire's, the only
substantial one in the organisation today. Everything else in AgStack documents
itself in a README, which is a content problem rather than a pipeline problem —
hence one real import rather than a speculative five.

The site is the documentation: sections live at the content root, so / is the
index itself rather than a splash page in front of it.

MECHANISM

Each documented repo is a git submodule under external/, pinned to a commit.
Hugo mounts its docs/ into assets/, and a content adapter turns those files into
pages. Two deliberate departures from the kernelci.org precedent this follows:

* Module mounts instead of tracked symlinks. Symlinked directories inside
  content/ are a fragile corner of Hugo that its maintainers have discussed
  removing, and kernelci is still pinned to Hugo 0.97.3 as a result.

* Mount into assets/ and generate pages, rather than straight into content/.
  Upstream Markdown has no front matter, and Hugo does not derive a title from
  the filename, so the direct mount yields a blank <title>, an empty Docsy <h1>
  above the document's own heading, and blank sidebar labels. The adapter takes
  the title from upstream front matter if present, else the leading H1, else the
  filename, and lifts that heading out of the body either way.

Importing GitHub-oriented Markdown charges two further taxes, both paid here:

* layouts/_markup/render-link.html rewrites repo-relative *.md cross-links to
  real permalinks. pancake had ten; all resolve.

* The adapter sets Docsy's github_repo / github_subdir /
  path_base_for_github_subdir page params. Adapter-generated pages do have a
  .File — it resolves to the adapter template — so without this, "View page
  source" and "Edit this page" send readers to _content.gotmpl instead of the
  Markdown they are reading.

Dependabot's gitsubmodule ecosystem bumps the pinned pointers weekly, which is
what stops imported docs from silently freezing at the commit they were added
at. `make update` is scoped to external/ so it cannot drag the theme off its
release tag.

RUNNING IT

Native: Node >= 24, and Hugo pinned in package.json via hugo-extended, so
nothing is installed globally. `make serve`.

Docker: `docker compose up serve` on a bare clone, with no host toolchain. The
entrypoint fetches submodules into the bind mount and installs the toolchain on
first run. Notable details, each of which cost a round to find:

* No named volumes. Docker creates a volume's mountpoint inside the bind mount
  as root, which blocks both the submodule checkout and npm ci for the
  unprivileged container user.

* node_modules therefore lives in the working tree, shared with the host — fine
  on Linux, a trap if installed on macOS or Windows, since hugo-extended and
  sass-embedded ship platform-specific binaries. The entrypoint tests that Hugo
  actually runs rather than that the file exists, and reinstalls if not.

* The bind mount carries :z. On an SELinux-enforcing host a checkout under $HOME
  is labelled user_home_t, which container processes may not read, so the mount
  fails with "Permission denied" despite being world-readable.

* Hugo is not baked into the image: `npm ci` installs the version pinned in
  package.json, so the container and a local checkout share one binary; CI will
  inherit that by running the same command.

BRANDING

Palette and marks derive from the AgStack logo, whose <style> block defines
exactly five fills: #0570d1 primary, #34a37e secondary, #1eafc6 info, #a3d641
warning, #2b2b2b body. $danger stays Bootstrap's red — none of the five reads as
"danger" and inventing one would make destructive states ambiguous. Bootstrap's
named $blue/$cyan/$green are set too, since Docsy's box and link utilities
resolve to those rather than the theme colours.

Measuring each SVG path's bounding box separated the mark from the wordmark
cleanly, giving a monochrome navbar mark, the full lockup for the landing page,
and a complete favicon set including a hand-built multi-resolution .ico.

LICENSING

A page keeps the licence of the repository it was written in; rendering a
document does not re-license it. Documentation authored here is CC BY-SA 4.0,
the site machinery is Apache-2.0, and imported pages carry their source's
licence — pancake is EUPL-1.2, so this is a real distinction rather than a
formality. Stated in the footer, on each imported page's banner, and in full at
/contributing/licensing/.

STATE

Verified with Hugo 0.166.0 extended and Docsy v0.17.0: 26 pages, zero build
warnings, every imported page titled and ordered from its own content, exactly
one <h1> per page, no unresolved cross-links, and repository links resolving to
agstack/pancake. Checked in a browser at 1400/900/390px in both colour modes. A
missing submodule fails the build with exit 1 rather than publishing empty
sections, and `make check` exits non-zero on an unresolved cross-link.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016mn32g3xvTVhT79ZVEbfUe

Author: padovan

.dockerignore

@@ -0,0 +1,4 @@
+# The image carries no project files — everything, including the entrypoint,
+# arrives at run time through the bind mount in docker-compose.yml. Keeping the
+# build context empty makes `docker compose build` independent of the working tree.
+*

.github/dependabot.yml

@@ -0,0 +1,40 @@
+version: 2
+
+updates:
+  # Bumps the pinned commit of every submodule under external/ and themes/.
+  #
+  # This is what keeps imported documentation from silently going stale: a
+  # submodule records an exact commit, so without these PRs the site would keep
+  # publishing whatever each component repo looked like on the day it was added.
+  # Each PR's diff is the upstream documentation change, which makes it a
+  # reasonable editorial review point rather than pure churn.
+  - package-ecosystem: "gitsubmodule"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps(submodule)"
+    labels:
+      - dependencies
+      - imported-docs
+
+  # Hugo (via hugo-extended) and Dart Sass.
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "deps(npm)"
+    labels:
+      - dependencies
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "deps(actions)"
+    labels:
+      - dependencies

.gitignore

@@ -0,0 +1,11 @@
+# Hugo
+/public/
+/resources/
+.hugo_build.lock
+
+# Toolchain
+/node_modules/
+
+# Editors / OS
+.DS_Store
+*.swp

.gitmodules

@@ -0,0 +1,7 @@
+[submodule "external/pancake"]
+	path = external/pancake
+	url = https://github.com/agstack/pancake.git
+	branch = main
+[submodule "themes/docsy"]
+	path = themes/docsy
+	url = https://github.com/google/docsy.git

Dockerfile

@@ -0,0 +1,35 @@
+# Build/preview container for the docs site.
+#
+# Hugo is deliberately NOT installed here. `npm ci` pulls the exact hugo-extended
+# version pinned in package.json, so this container and a local checkout build with
+# the same binary — one place to bump it, and no drift between "works in Docker"
+# and "works on my machine". CI, once this repository has any, inherits that for
+# free by running the same `npm ci`.
+#
+# Node 24 / npm 11.18 are Docsy v0.17's stated minimums.
+FROM node:24-bookworm-slim
+
+# git is not needed to build the site (enableGitInfo is off), but the entrypoint
+# reports on submodule state and contributors expect it to exist in the shell.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+
+# uid 1000, matching the typical host user, so everything written into the bind
+# mount — node_modules, public/, resources/, and the fetched submodules — stays
+# owned by the person running docker rather than by root.
+USER node
+
+EXPOSE 1313
+
+# The entrypoint is read from the bind mount rather than copied into the image, so
+# editing it takes effect on the next `docker compose up` with no image rebuild.
+# The image is useless without the mount anyway — it carries no site content.
+#
+# Invoked through `sh` rather than executed directly, so it does not depend on the
+# execute bit surviving however the tree reached the host (archive extraction, a
+# copy across filesystems, a Windows checkout).
+ENTRYPOINT ["/bin/sh", "/src/docker-entrypoint.sh"]
+CMD ["npm", "run", "serve"]