Design — internal doc space styling & navigation

Date: 2026-06-29 · Owner: Claude (build) + Jonathan (review) · Status: Design approved — implementation plan pending Builds on: the live doc space (it/2026-06-25-internal-doc-space-{design,plan}.md). This is a follow-on styling/navigation pass, internal tier only.

The need

The Markdown-rendered pages on board.cloudbase.foundation render through a bare base.liquid (just <main class="doc-main">{{ content }}</main> + the inlined theme). They get the brand typography but no site chrome — no masthead, no footer, no navigation — so they look unfinished next to the bespoke showcase HTML pages (domain-map, roadmap, the agendas), and the doc space reads as a pile of standalone pages rather than a navigable site. This pass adds a branded baseline template and real navigation so the internal space feels cohesive.

Decisions (locked)

Scope: internal (board.*) tier only. The public (public.*) tier stays bare for now. The chrome is tier-gated, so public pages are byte-for-byte unchanged.
Approach A (of three considered): one tier-aware shared layout + a reusable nav component + Eleventy collections for auto-listed section pages. Explicitly not a separate internal layout (B) and not full docs-grade breadcrumbs/prev-next/ active-highlighting (C).
Chrome lives in base.liquid, guarded by {% if tier == "internal" %}: a branded masthead (CBF wordmark + nav) and a footer/colophon. The internal build sets tier: "internal" as global data; the public build leaves it unset → public output unchanged.
Top nav is hand-curated via _data/nav.json. Items: Home · Agendas · IT & Ops · Research · Reference (Reference groups the tech showcase pages + the components ref). resumes/ and foundational/ are deliberately not top-nav items.
Auto-listed section landing pages. Eleventy collections by directory generate /agendas/, /it/, /research/ (and other configured sections), each rendered by one shared listing template (doc title + date, newest first). New docs appear with no manual index editing. The curated index.md remains the homepage/dashboard.
Nav is a self-contained component — _includes/site-nav.html plus nav styles, with the component carrying its own scoped CSS so it can be dropped into pages that do not include theme.css (the showcase pages). Used by the layout and injected into the standalone HTML pages.
Showcase HTML pages keep their bespoke design. tech/domain-map.html, tech/roadmap.html, and the agendas/*.html files get the site-nav component injected at the top of <body> (markup + scoped CSS); their embedded <head>/<style> and body layout are otherwise untouched.
Theory of Change relocates to the internal tier. Move public/theory-of-change.md → foundational/theory-of-change.md so it picks up the new chrome and can be styled. public/index.md is updated to mark ToC "coming soon." The public URL public.cloudbase.foundation/theory-of-change/ will 404 in the interim — an accepted, temporary tradeoff; ToC returns to public/ when the public-site work resumes.

Architecture

base.liquid  (shared by both builds)
│
├── tier == "internal"  → masthead (wordmark + nav) + <main> + footer/colophon
│        nav links from _data/nav.json; section pages from collections
│
└── tier unset (public) → current bare <main> only   [public output unchanged]

site-nav component  (_includes/site-nav.html + scoped CSS)
│
├── used inside base.liquid (internal chrome), and
└── injected into the standalone showcase HTML pages (verbatim body preserved)

Eleventy collections (by directory)  →  /agendas/, /it/, /research/, …  (shared listing template)

Internal build (eleventy.config.js): sets tier: "internal", registers the section collections, builds the listing pages, keeps the existing showcase passthroughs.
Public build (eleventy.public.config.js): unchanged inputs (public/ only), no tier flag → no chrome. Leak posture is preserved by the existing input scoping.

Components (files)

File	Change	Purpose
`_includes/base.liquid`	modify	Add tier-gated masthead + footer; render nav from `_data/nav.json`
`_includes/site-nav.html`	create	Reusable nav component (markup)
`_includes/theme.css`	modify	Append masthead/footer/nav styles (reuse existing tokens)
`_data/nav.json`	create	Curated top-level nav links
`_includes/section-list.liquid` (or similar)	create	Shared listing template for section landing pages
`eleventy.config.js`	modify	Set `tier` global data; register directory collections + landing pages
`tech/domain-map.html`, `tech/roadmap.html`, `agendas/*.html`	modify	Inject `site-nav` at top of `<body>`
`foundational/theory-of-change.md`	move (from `public/`)	Relocate ToC to internal tier
`public/index.md`	modify	Mark ToC "coming soon" (remove the now-internal link)

Implementation considerations (resolve in the plan)

Injecting nav into passthrough HTML. The showcase/agenda pages are addPassthroughCopy verbatim and carry their own embedded CSS (they do not include theme.css). The nav component therefore ships self-contained styles. Whether to hand-edit each file or run them through Eleventy with a partial include is a plan-level call; if processed, guard against stray {{/{%/Mermaid braces.
Which directories get section landing pages (and their human labels/order) is fixed in the plan alongside _data/nav.json.
markdownTemplateEngine stays off for content; only the Liquid layout/includes use templating, exactly as today.

Non-goals

Public-tier chrome/navigation (deferred to the public-site work).
Breadcrumbs, prev/next, active-link highlighting (Approach C).
Brand-system changes — colors/fonts/tokens are reused as-is, not revised.
Sidebar navigation.

Risks & rollback

Tier leak / public drift → the chrome is tier-gated and the public build's input is scoped to public/; re-run the existing leak checks after the change. Public output must stay identical.
Showcase nav-injection brace-safety → if the HTML pages are processed rather than hand-edited, a stray brace could break the build; mitigate per the plan.
ToC public takedown → accepted and temporary; the public/index.md "coming soon" edit prevents a dead link on the public site.
Rollback → all changes are in the repo; revert the commit(s). No hosting/DNS/Access changes are involved.