structure

Structure

Every set of documentation this plugin produces uses this layout. It is not chosen per repo and it is not negotiable, because a reader who learns where things live in one product should find them in the same place in the next.

The model is Harvester: Docusaurus, a sidebar generated from the filesystem, and subject-first directories.

The tree

docs/
├── index.md                    slug: /, the one-sentence answer to "what is this"
├── faq.md
├── getting-started/            position 2
│   ├── overview.md
│   ├── glossary.md             every term a newcomer will not know
│   └── document-conventions.md how to read the rest
├── install/                    position 3, one page per target
├── <subject>/                  positions 4 upward, one per thing in the product
│   ├── _category_.json
│   ├── <anything>.md           the landing page, marked sidebar_position: 1
│   └── <verb>-<noun>.md        one task per page
├── api/                        position 90, only when there is a spec to generate from
├── advanced/                   position 91
├── troubleshooting/            position 92
└── developer/                  position 93

Plus up to four cross-cutting pages at the root beyond index.md and faq.md, for a topic that genuinely spans every subject. Harvester has two, airgap.md and authentication.md. More than four means a subject was never named.

Scaffold it rather than creating it by hand:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py init \
  --title "Name" --description "one sentence" \
  --subject "vm:VM Management,volume:Volumes" --site --api \
  --url https://docs.example.com --org owner --project repo \
  --edit-url https://github.com/owner/repo/edit/main/
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py check

Pass --api only when survey.py found an OpenAPI spec. Harvester's docs/api is generated at build time from its swagger files by docusaurus-plugin-openapi-docs, so an empty api/ on a product with no spec is a section nobody can fill.