docs: Add page descriptions to the Kubernetes, concepts and guides pages#895
Open
lfrancke wants to merge 3 commits into
Open
docs: Add page descriptions to the Kubernetes, concepts and guides pages#895lfrancke wants to merge 3 commits into
lfrancke wants to merge 3 commits into
Conversation
27 pages had no :description: attribute, so search engines and the generated llms.txt fall back to nothing or the raw title. Skipped on purpose: modules/concepts/pages/stackable_resource_requests.adoc is an include target published as a page; a :description: entry there would leak into every including page and override their descriptions.
✅ Deploy Preview for stackable-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
The internal module was never registered in the antora.yml nav and nothing links to it, but Antora still published it at /internal/personas/. Internal working material does not belong on the public docs site.
The internal module is deleted on main, but the release branches still contain it and Antora publishes their content too. A forced netlify 404 covers all versions at the serving layer without backporting the deletion.
Techassi
requested changes
Jul 23, 2026
Techassi
left a comment
Techassi
left a comment
Member
There was a problem hiding this comment.
Most of the descriptions for pages under pages/kubernetes feel a little off. I like the ones in the style of "Notes on ...".
Others feel a too "tutorial-like". I also think that they shouldn't include details like "You need to do this" or "Custom stuff is needed because ...".
| @@ -1,4 +1,5 @@ | |||
| = Amazon Elastic Kubernetes Service (EKS) | |||
| :description: Run the Stackable Data Platform on Amazon Elastic Kubernetes Service (EKS). Make sure a default StorageClass is set so PVCs are provisioned. | |||
Member
There was a problem hiding this comment.
The "make sure..." part of the description seems a little off. It doesn't feel like it should be part of the page's description/overview.
| @@ -1,3 +1,4 @@ | |||
| = plusserver Kubernetes as a Service | |||
| :description: Notes on running the Stackable Data Platform on plusserver Kubernetes as a Service. | |||
Member
There was a problem hiding this comment.
Suggested change
| :description: Notes on running the Stackable Data Platform on plusserver Kubernetes as a Service. | |
| :description: Notes on running the Stackable Data Platform on plusserver's Kubernetes as a Service. |
| # branches; this blocks it for every published version without backports. | ||
| [[redirects]] | ||
| from = "/home/:version/internal/*" | ||
| to = "/404.html" |
Member
There was a problem hiding this comment.
I would like to avoid redirecting to .html files as these redirects always cause issues. We should instead use:
Suggested change
| to = "/404.html" | |
| to = "/404" |
Techassi
moved this from Development: Waiting for Review
to Development: In Review
in Stackable Engineering
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds
:description:attributes to the 27 user-facing pages in this repo that had none (the Kubernetes distribution pages, the concepts maintenance/observability pages, the CRA page, the guides pages, the release guide).The reason I added these is that I want them to show up in
llms.txt.Each description was written from the page content. I used AI to generate all of them, but I looked at them and think they are good enough.
Two deliberate omissions:
modules/concepts/pages/stackable_resource_requests.adoc- it is an include target that also gets published as a page; a:description:there would leak into every including page (e.g. concepts/resources) and override their descriptions. Candidate for moving topartials/some day.The remaining description gaps live in the operator repos, stackablectl and demos.
This also removes the personas page which we never really used.