Skip to main content

Publishing

How to get a document live on this site.

Global rule (owner, 2026-09-29): every artifact generated for owner review — reports, briefs, review packets, receipts, deliverables, work records — is published to this site before it is considered delivered. Put it in the correct category, run the metadata and strict candidate-build gate, verify its live route, and push the reviewed source. The nightly host job can commit/push through the same gate; an external agent follows the PR or authorized-push path and waits for exact-commit CI plus host publication.

The publication gate at a glance (the prose below governs):

The host publication gate​

On jkdev001, after editing docs/ or src/, run from the repository root:

bash scripts/validate-and-build.sh

The gate validates every Markdown file's four-axis metadata (including archived files), builds with strict MDX/link/anchor/tag settings into a separate directory, and atomically changes the served build pointer only after success. A failed candidate leaves the prior site serving. Check the command's exit code and read back the new page. The host's pull and push jobs use this same gate; an external agent never runs Docker on the site host. Config or Dockerfile changes require a new image and controlled container replacement before the gate can run against the changed settings.

Where things go​

docs/
├── index.md             # this landing page
├── 01-reports/          # dated deliverables, review queue
├── 02-research/         # Research Hub outputs
├── 03-projects/         # per-product docs
├── 04-fleet/            # agent orchestration ops
├── 05-compliance/       # M365 / CIS
├── 06-architecture/     # specs, ADRs, capability maps
├── 08-standards/        # document / evidence / release standards
├── 09-runbooks/         # step-by-step procedures
├── 10-catalogs/         # source / tooling / deliverable registers
├── 11-templates/        # fill-in files
├── 12-tooling/          # generator docs (usage, versioning)
├── 13-voice/            # writing standard, finding sentences
└── 14-knowledge/        # this guide, site conventions, verified tool/protocol facts

Each folder's index.md is the category landing page (auto-sidebar category).

Ordering (owner rule, 2026-09-29, refined same day)​

Everything is kept in order by two layers:

  1. Top level: categories display in alphabetical order (Architecture → Catalogs → Compliance → Fleet → … → Voice). The visible labels are what you navigate by, so the on-screen order must read as alphabetical — that's why the sidebar rank is set explicitly per category (each index.md carries sidebar_position: N = its alphabetical slot). The NN- folder prefix is storage-only now: it keeps the folder names stable and unambiguous on disk, but it no longer drives display order. Don't renumber folders to change order — change the sidebar_position.
  2. Within a category: alphabetical by filename (Docusaurus auto-sort). Reports are named YYYY-MM-DD-slug.md, so filename order is chronological order — newest date last.

So you get categories in alphabetical order and documents within each category in filename order. Dated reports happen to sort chronologically; evergreen documents sort by their ordinary filenames.

  • Landing pages sort by their rank within their own category slice; the top-level index.md (site home) still appears first overall.
  • New docs just appear in the right date slot. No position juggling.

Dates in names (owner rule, 2026-09-29)​

Yes — date the point-in-time things. Reports and dated deliverables are named YYYY-MM-DD-slug.md (in 01-reports/, or where they belong). The date prefix is what keeps them in chronological order and keeps them unambiguous when many similar reports exist. It's the primary sort key; tags are the secondary index.

Use dates for anything with a "when." Ongoing evergreen docs (a standard, a runbook, a reference) do not carry a date — they are current, not a point in time, and dating them would be misleading.

Archiving & pruning point-in-time content (owner rule, 2026-09-29)​

You generate a lot of point-in-time content — review it, glean the info, move on. Docusaurus has no built-in "prune," but we use a three-tier lifecycle:

  1. Live — in the category, in the sidebar. Current and worth navigating to.
  2. Archived — move the file into <category>/_Archive/. It stays on disk (the dir is bind-mounted, so you can still open or diff it) but is excluded from the build and navigation. This is the default for a report you've finished with: git mv docs/01-reports/2026-09-28-foo.md docs/01-reports/_Archive/ then rebuild. Moving it back out of _Archive/ is the explicit "this is current again" act.
  3. Pruned — genuinely delete (a separate, deliberate act). Only for content with no future value. Archived content is cheap to keep (it's just git history + a file), so archive first; prune only on purpose.

Practical default: when a report's review is done, move it to _Archive/. The _Archive/ exclusion is already wired into docusaurus.config.js (exclude: ['**/_Archive/**']), so no config change is needed to archive. A cited historical report may remain live for traceability if it is prominently marked superseded in its body and has status-superseded. The dated Docusaurus taxonomy proposal, initial bring-up and sync reports are retained this way so review links remain usable. None is operative guidance.

File rules​

  • One document per file.
  • Reports / dated deliverables: YYYY-MM-DD-slug.md in the right category.
  • Ongoing docs: slug.md in the right category.
  • The URL normally includes the category route and the document ID, for example /docs/knowledge/agent-publishing or /docs/reports/<dated-id>. Use the actual built route; slug may override it. Numbered storage prefixes are stripped from the public category path.
  • Archiving — see the lifecycle above: _Archive/ to hide, separate act to delete.

Front matter​

---
id: agent-tailscale-host
title: "Agent host: Tailscale access runbook"
tags: [runbook, tailscale, category-runbooks, status-current]
---

Every Markdown document, including category indexes and archived files, needs ordered type, one or more topics, a folder-matched category and a status. See Document taxonomy. A separate review type means an independent assessment; status-draft signals owner review.

Pitfalls (already handled — don't relearn them)​

  • docs/ and src/ are bind-mounted into the container, so the in-container build sees both. You never need a new image to publish a doc.
  • If the docsite container is not running, diagnose its status and startup logs before rebuilding or recreating it. Do not remove a container as a first step.
  • The nightly cron (portals-landing-page, 02:00 CST) regenerates the Portals page only — it does not touch docs/.

Published by Hermes · 2026-10-01.