docs: pilot split of github.md into operator-facing + collapsed implementation
hyperhive#3902, mara: option (a) - a content pass splitting mixed docs into operator-facing content plus implementation detail. One file first, to agree on the split pattern before doing the other ~19. Went through 3 shapes on review before landing here: a sibling -internals.md file (mara: clutters the navigation), then two tree-precedent alternatives damocles raised (subdir+README like web-ui/; or only split docs with a pre-existing boundary marker, which would've covered 3-4 of the ~20 flagged docs and left the rest untouched), then mara's own proposal - a collapsed <details> section in the same file. Verified empirically (cmark-gfm --unsafe, the website's own render pipeline) that markdown headings nested inside a <details> block still parse as real headings with heading-id anchors once separated from <summary> by a blank line, so anchor links into the collapsed section keep working. github.md keeps enabling/provisioning/security up top; its 'Implementation' section is now a <details> block holding what was briefly a separate github-internals.md (deleted again) - how the agent's gh/git-push actually authenticate, and the notification poller's internals. Reverted the two cross-references + the docs/README.md entry back to pointing at github.md now that the content lives there again. Added a short CLAUDE.md note recording the pattern per mara's ask, including the one real caveat damocles flagged: <details> only collapses in a rendered browser, a raw-text read (cat, the Read tool) still sees everything, same as today.
This commit is contained in:
parent
0824caaa2b
commit
67207ae32f
3 changed files with 21 additions and 5 deletions
|
|
@ -209,3 +209,12 @@ with each other.
|
|||
thing is, not to how much investigation it took to find it — a
|
||||
mechanical fix gets a one-line comment, a genuinely non-obvious
|
||||
invariant or decision earns real prose.
|
||||
- **Operator-facing doc with real implementation detail mixed in**: wrap
|
||||
the implementation part in a `<details><summary>…</summary>` block
|
||||
(blank line after `<summary>` so the markdown inside still renders,
|
||||
not a second file) rather than splitting into a sibling page — see
|
||||
`docs/integrations/github.md`'s "Implementation" section. Zero nav
|
||||
churn, works uniformly regardless of whether the doc already had a
|
||||
clean boundary. Caveat: it only collapses in a rendered browser —
|
||||
reading the file as raw text (`cat`, the Read tool) shows everything,
|
||||
same as today.
|
||||
|
|
|
|||
Loading…
Reference in a new issue