Skip to content

ADR — Content excluded from the published site

  • Date: 2026-04-27
  • Status: Accepted
  • Project: engineering-docs-site

Decision

The following paths are excluded from the rendered MkDocs site, even though they remain in the git repo:

  • _archive/ — closed-out projects retained for history
  • _proposed/ — pre-execution drafts
  • **/code/ — code mirrors inside any project
  • **/inputs/ — source materials, exports, screenshots inside any project

Everything else under projects/ and platform/ is included.

Context

The repo holds more than what readers should see in nav. Several categories of content support the work but are not "the work":

  • _archive/ is reference; surfacing it in the active nav would clutter and mislead.
  • _proposed/ would prematurely broadcast ideas that haven't been committed to. Reviewers can still see proposals via PR preview deployments — they just don't appear in the production nav.
  • code/ subfolders inside a project hold mirrors of what's actually authored in a separate repo; surfacing them in the docs nav is noisy and rarely the right reading order.
  • inputs/ holds raw materials (CSV exports, screenshots, vendor PDFs) that informed the plans. Useful adjacent to the Markdown but not part of the readable narrative.

ADRs (decisions/) and handoff prompts (handoff/) ARE included — they're load-bearing context for understanding why a project went the way it did.

Consequences

Positive:

  • Cleaner nav. Readers see plans, runbooks, ADRs, handoff prompts — the readable artifacts.
  • Excluded content is still in the repo, still version-controlled, still discoverable by a colleague who clones.
  • Reviewers can see drafts on PR preview deployments by un-excluding _proposed/ temporarily on a branch — the exclusion is a config choice, not a destructive one.

Negative / accepted trade-offs:

  • A reader who wants to look at a project's inputs/ has to clone the repo. Acceptable — those readers are engineers, and inputs are rare-to-need.

Implementation

In mkdocs.yml:

exclude_docs: |
  _archive/
  _proposed/
  **/code/
  **/inputs/

(Plus .gitignore excludes build artefacts like site/, .venv/, __pycache__/, .DS_Store.)

Reversibility

Any of these can be re-included by deleting one line from mkdocs.yml. There is no migration cost to revisit.

Future consideration

If _proposed/ content benefits from being internally visible (drafts collaborative across the team) without being committed-as-final, the right move is to publish a separate "drafts" subdomain (e.g. drafts.adventive.dev) with the same Access policy, built from a drafts branch. Defer until requested.