How to add a new resource to the internal service documentation

Directory tree

docs/internal/
        ├── README.html                 # Entry: overview, service scope, ADRs, links (API hub, etc.)
        ├── STRUCTURE.md                # Stub → links to this page (howto)
        ├── service-overview.html       # Redirect stub → README.html (bookmarks)
        └── api/
        ├── README.html             # HTTP API hub — list of resources
        └── user/                   # One folder per API resource name
        ├── index.html          # Hub: business, contract, technical spec, method index
        ├── user-http-api.html  # Optional redirect stub → index.html (bookmarks)
        └── operations/         # One HTML file per HTTP endpoint (not per operationId)
        ├── post-api-v1-user.html
        ├── get-api-v1-user-system_uuid-system_user_id.html
        ├── put-api-v1-user-system_uuid-system_user_id.html
        └── patch-api-v1-user-system_uuid-system_user_id.html

Shared chrome

Every internal page that should show the sidebar: load internal-layout.css + internal-sidebar.js, include #internal-sidebar-mount, and use the shell markup (see internal/README.html).

Page structure (On this page, Overview, sections)

Multi-section pages that use the internal sidebar layout should follow one predictable skeleton so navigation and scanning stay consistent. Canonical example: docs/internal/README.html.

Recommended order inside .container

1. <h1> — page title. If this file is the sidebar entry labeled Overview (internal/README.html), prefer a title that matches that role (e.g. “Welcome — Internal docs”).
2. <div id="docs-top-nav"></div> — top “pill” navigation (from docs-nav.js).
3. Optional <p class="lead"> — one short paragraph when the page needs a hook before the table of contents.
4. Overview — on hub / landing pages, the first substantive block is usually <section id="overview" class="card"> with <h2>Overview</h2>: who the page is for, what to open next, and links to System design, Developers Docs, API hub, OpenAPI, etc. Omit or replace with a different first <h2> when the document is not a map (e.g. System design uses numbered top-level sections).
5. Additional topics — more <section id="..." class="card"> blocks, one main subject per card.
6. <div class="docs-inpage-toc-mount" data-inpage-toc="auto"></div> near the end of the container — injects the auto-generated On this page TOC from headings. If this mount is missing, docs-nav.js adds it automatically.

How to add a new resource (e.g. Order)

1. Create docs/internal/api/<resource>/index.html (hub) and docs/internal/api/<resource>/operations/ for endpoint pages.
2. Name operation files from HTTP method + path template, e.g. get-api-v1-orders--order_id.html — not from Python operationId.
3. Extend INTERNAL_SIDEBAR_NAV in internal-sidebar.js (paths from docs/ root, e.g. internal/api/order/index.html).
4. Add a card + link on internal/api/README.html.
5. Put business + technical narrative on the resource index.html (see internal/api/user/index.html). Add <resource>-http-api.html only as a redirect stub if you rename later — follow ADR 0026 (same PR as behavior changes).

How to edit existing pages

• Sidebar: change labels or paths in INTERNAL_SIDEBAR_NAV in internal-sidebar.js.
• Top navigation (Home, Internal, …): edit renderTopNav in docs-nav.js.
• Page body: edit the HTML file; run make docs-fix if your workflow includes doc sync and format checks.

Removed / obsolete

• docs/internal/user/ — removed; the canonical User hub is api/user/index.html.
• details.internal-doc-map styles were removed from docs.css (old collapsible map on README).
• internal-doc-demo.css / internal-doc-nav.js — removed; they only served a deleted prototype page.

Related

• Page structure (On this page, Overview, sections) — on this page
• Documentation style guide and audit standard — cross-doc rules and templates
• Internal service documentation — index
• ADR 0025 — external vs internal API documentation
• ADR 0026 — internal narrative as source of truth
• How-to guides — index

Page history