Skip to content

Add the generated command pages to the nav, serve Markdown - #496

Merged
bonus414 merged 4 commits into
mainfrom
llm-readable-docs
Aug 5, 2026
Merged

Add the generated command pages to the nav, serve Markdown#496
bonus414 merged 4 commits into
mainfrom
llm-readable-docs

Conversation

@bonus414

Copy link
Copy Markdown
Contributor

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.

@bonus414
bonus414 requested review from CGoodwin90 and bomoko July 30, 2026 19:33
@bomoko
bomoko requested a review from shreddedbacon July 30, 2026 19:36
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.
Comment thread mkdocs.yml
Comment on lines +46 to +49
- llms-source:
description: >-
Documentation for the Lagoon CLI, the command line client for the
Lagoon application delivery platform.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.
Image

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread mkdocs.yml Outdated
- Getting Started: index.md
- Configuration: config.md
- Commands: commands/lagoon.md
- Commands:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change also makes the drop down menu for the commands in the ToC massive.

Image

It would be better if the command verbs were folders, this way the menu would probably be more palatable. But as the docs are autogenerated, this may not be a straightforward change to make.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

bonus414 and others added 3 commits July 31, 2026 11:07
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>
@bonus414
bonus414 merged commit 432199b into main Aug 5, 2026
8 checks passed
@bonus414
bonus414 deleted the llm-readable-docs branch August 5, 2026 12:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants