| .. | ||
| extensions | ||
| modules | ||
| accounts-dark.png | ||
| accounts-light.png | ||
| anaconda.md | ||
| antora.yml | ||
| authentication.md | ||
| branding.md | ||
| cockpit-system-apis.png | ||
| cockpit-system-apis.svg | ||
| cockpit-transport.png | ||
| cockpit-transport.svg | ||
| i18n.md | ||
| key-auth.md | ||
| login.md | ||
| Makefile-doc.am | ||
| Makefile-guide.am | ||
| Makefile-man.am | ||
| networking-dark.png | ||
| networking-light.png | ||
| overview-dark.png | ||
| overview-light.png | ||
| protocol.md | ||
| README.md | ||
| routing.md | ||
| urls.md | ||
Cockpit Docs
We have two distinct workflows for our docs, one relates to bundling documentation within Cockpit packages, the other regards online documentation for Cockpit with features for ease-of-use.
Explanation of existing directories and what their purpose is. Mostly follows an Antora designated directory design that is explained in Antora folder structure.
doc/ # All of Cockpit's doc is here; Plugins should be excluded.
├── modules # Antora expects a module structure, irrelevant for AsciiDoctor.
│ ├── guide # Cockpit Guide docs, encompasses everything that relates to Cockpit
│ │ ├── bundling # Specific to AsciiDoctor bundling where we put single-page wrappers
│ │ ├── pages # All pages that relate to Cockpit itself
│ │ └── nav.adoc # Antora navigation file, displays pages from the file as a sidebar navigation for the specific component
│ └── man # Cockpit man pages. Packaged as Manpages with AsciiDoctor, HTML with Antora.
│ ├── pages # All manpages for packages distributed in cockpit
│ ├── partials # Antora-designated folder, partials are imported by AsciiDoc manpages for Bugs, and Author
│ └── nav.adoc # Antora navigation file, displays pages from the file as a sidebar navigation for the specific component
└── antora.yml # Config for Antora to pickup that designates navigation files and attributes
Antora folder structure
Since Antora is a versatile documentation tool, they have structured directories for managing the modules and module-specific features - like pages and attachments.
Antora assigns preset, content-specific behavior to the source files stored in the family directories.
https://docs.antora.org/antora/latest/family-directories/
Local testing
We do not need to run Antora from cockpit-docs repo to make updates here, instead you can run Antora from NPM to compile it, then simply open the output or run a http server.
With NPM
npm exec antora generate antora-playbook.yml
With PNPM
pnpx antora generate antora-playbook.yml
You'll get an output for site generation completed followed by a file to open. If you run Flatpak you might have to run a simple server instead
python -m http.server -d ./doc/output/antora