Skip to main content
The rules every page on this site follows. Author to these by default; when a rule and a page disagree, fix the page.
This page is the canonical standard for docs.jacobpevans.com. It exists so new pages land consistently no matter who — human or model — writes them.

​
Information architecture

The site is organized by domain, not by document type. The left sidebar has a small set of top-level dropdowns (Overview, Homelab infrastructure, Platform and tooling, AI and agents, Security and secrets, Reference). A reader picks a domain first, then narrows. Document type (the Diátaxis idea of tutorial, how-to, reference, explanation) is captured as page metadata — the page_type field below — not as navigation groups. Nesting docs under “How-to” / “Reference” headings suits a product with large workflows; this site is an ecosystem map for one reader, so domain-first navigation scans faster.

​
Page naming

SurfaceRule
FilenameLowercase kebab-case. It is the URL slug — they never differ.
overview.mdxOnly for a group’s landing page.
TitleSentence case: capitalize the first word and proper nouns only. Never a raw slug.
AmpersandUse “and” in titles and labels. Keep & only inside an official product name.
Preserve these tokens exactly, wherever they appear in a title: AI · API · AWS · BMC · CI/CD · DNS · GPU · HEC · IAM · IaC · IDS · IPS · K8s · LLM · LXC · macOS · MCP · MFA · MLX · MoE · Nix · OIDC · OTEL · OTLP · PR · README · SIEM · SOPS · TTL · UniFi · VLAN · VMID · VPN · YAML · ZFS — plus proper nouns kept in their own casing: Apple · Bifrost · Bitwarden · ChatGPT · Cribl · Docker · Doppler · GitHub · Keychain · Kubernetes · Mac · OpenBao · OpenTofu · OrbStack · Proxmox · Splunk Renaming a file changes its slug. When you rename or move a page, add a redirects entry in docs.json (old → new) and update every inbound link so none rely on the redirect.

​
Frontmatter

Every content page starts with: 
---
title: "Sentence case, acronyms preserved"
description: "One sentence: what the page helps you do or understand."
page_type: "reference" # one of: overview, how-to, explanation, reference, decision, repo
---
page_type records what the page is trying to do. Pick one:
page_typeUse for
overviewA group’s landing page: mental model and route map.
explanationHow something works and why — architecture, rationale.
how-toStep-by-step setup or operation.
referenceCanonical tables, policies, naming rules, per-tool detail.
decision”Why this way” — the tradeoff behind a choice.
repoA single public repo explainer with source links and contracts.
Keep the sidebar scannable:
  • A dropdown shows at most ~3 group headers at once.
  • A group with more than ~6 pages splits into collapsible subgroups.
  • Nest at most two levels deep below a dropdown.

​
Writing style

Follow the Google developer documentation style guide: short sentences, one idea each, active voice, second person (“you”), sentence-case headings. Keep terms of art, but define each the first time you use it. The full voice-and-tone rules live in the repo’s AGENTS.md.

​
Sources

These standards derive from established documentation practice:
SourceWhat it informs
DiátaxisThe four document types, captured here as page_type.
Divio — The documentation systemThe same four-type model, applied to structure.
Google developer documentation style guideSentence case, active voice, plain language.
Write the Docs — Documentation GuideGeneral authoring and maintenance practice.
Nielsen Norman Group — menu configurationsNavigation density and scannability.
Mintlify navigationDropdowns, groups, and how this site’s sidebar renders.