Add the generated command pages to the nav, serve Markdown - #496
Conversation
The docs directory contains a generated page for every command, but the nav referenced only commands/lagoon.md, so the remaining 153 command pages were built without appearing in the navigation. This uses awesome-pages to include the whole commands directory. Also publishes each page as raw Markdown alongside the rendered HTML (/foo/bar/ -> /foo/bar.md) and generates llms.txt and llms-full.txt, so the command reference can be read directly by LLM-based tools. Adds docs/requirements.txt and points the publish workflow at it via REQUIREMENTS. The workflow previously installed no extra dependencies, so there was nowhere to declare the plugins the config now uses. Verified with mkdocs build --strict on both the native build used for publishing and the amazee.io container image: 156 pages served as Markdown, up from 4.
e5a702d to
4779444
Compare
| - llms-source: | ||
| description: >- | ||
| Documentation for the Lagoon CLI, the command line client for the | ||
| Lagoon application delivery platform. |
There was a problem hiding this comment.
| - llms-source: | |
| description: >- | |
| Documentation for the Lagoon CLI, the command line client for the | |
| Lagoon application delivery platform. | |
| - llms-source: | |
| description: >- | |
| Documentation for the Lagoon CLI, the command line client for the | |
| Lagoon application delivery platform. | |
| homepage_notice: false |
My only gripe is that this banner is present right at the top and is not configurable where it lands, or how much space it takes up, see documentation. If it was configurable to move to the bottom or somewhere else like footer, then it might be ok.

Otherwise the notice can be removed, if its absolutely required, could we add it into the footer or somewhere in the index.md file manually?
There was a problem hiding this comment.
Turned it off in 7b6cefb. I checked the plugin's config — the notice is on/off only, no placement control, and llms.txt generation doesn't depend on it. If we want a pointer for agents later, a manual line in index.md would do it.
| - Getting Started: index.md | ||
| - Configuration: config.md | ||
| - Commands: commands/lagoon.md | ||
| - Commands: |
There was a problem hiding this comment.
There was a problem hiding this comment.
This turned out to be straightforward without touching the generated files — nav structure doesn't have to mirror the file layout. --docs now also writes a docs/commands/.pages file grouping pages by verb, and awesome-pages builds the nav from it: 21 top-level entries instead of 153. Bonus: llms.txt derives its sections from the nav, so it picks up the same grouping. Nothing moves on disk, so cross-page links are unchanged.
The banner isn't configurable for placement and llms.txt generation doesn't depend on it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
153 flat entries under Commands made the dropdown unusable. The docs generator now also writes a .pages file grouping pages by their verb (add, list, delete, ...), which awesome-pages uses to build the nav — and llms.txt inherits the same structure. No generated files move, so cross-page links are untouched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The docs folder has a generated page for every command, but the nav pointed
at only one of them, so the other 152 were published without appearing in
the navigation. This pulls the whole commands folder in.
Also publishes each page as plain Markdown plus an llms.txt index, so AI
tools can read the command reference directly.
The publish workflow installed no doc dependencies, so there was nowhere to
declare the plugins the config now needs. Adds docs/requirements.txt and
points the workflow at it, same as uselagoon/lagoon does.
Strict build passes both ways. 156 pages published as Markdown, up from 4.
Note the docs publish on version tags, so this appears at the next release.
CI's container step will fail until the plugin lands in the mkdocs-material
image.