Skip to content

docs: bring CLI docs up to Elastic Docs conventions#406

Open
theletterf wants to merge 11 commits into
elastic:mainfrom
theletterf:docs/elastic-docs-conventions
Open

docs: bring CLI docs up to Elastic Docs conventions#406
theletterf wants to merge 11 commits into
elastic:mainfrom
theletterf:docs/elastic-docs-conventions

Conversation

@theletterf

@theletterf theletterf commented Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • Add required frontmatter (type, applies_to, description) to all four docs pages; products left out pending an official product ID for this new CLI
  • applies_to: stack: preview / serverless: preview on all pages, reflecting the CLI's current experimental status and support for both deployment types
  • Restructure installation.md and configuration.md as proper how-to pages: action-verb H1 titles, Before you begin prerequisites, numbered steps, success checkpoints (elastic --version, elastic status), and Next steps links
  • Expand the cli/index.md overview stub with a brief capability summary and use-case list; remove the embedded instructional sentence (belongs in a how-to)
  • Style fixes from Vale + manual review: execute → "run", e.g. → "for example,", passive voice, Oxford comma, unformatted binary name, ambiguous "Either flag"

🤖 Generated with Claude Code

@theletterf @claude
docs: bring CLI docs up to Elastic Docs conventions
0af2e87 
Add required frontmatter (type, applies_to, description), fix content
type structure for how-to pages (action-verb titles, Before you begin,
success checkpoints, Next steps), improve overview stubs, and apply
Vale-flagged style fixes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf

theletterf commented Jun 9, 2026

Copy link
Copy Markdown
Member Author

@JoshMock @Mpdreamz Merging this should trigger our first docs preview deployment (just a preview, no docs published on the site or anything like that).

theletterf and others added 2 commits June 9, 2026 18:04
@theletterf @claude
fix(docs): add missing namespace index pages and regenerate NOTICE.txt
8e550ae 
docs-builder generates shortcut alias pages (es, elasticsearch, kibana)
that link to /cli/stack/es/ and /cli/stack/kb/ but never produces those
namespace index pages from the schema. Adding stub pages at those paths
resolves the broken-link build error.

NOTICE.txt was also out of date; regenerated via generate-notice.mjs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
fix(docs): add stack/es and stack/kb index pages to TOC
eca2283 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @cursoragent
fix(docs): omit shortcut redirects from cli schema
38a917f 
Docs-builder generates broken alias pages from the non-standard shortcuts field, while runtime CLI shortcuts continue to be handled by argv rewriting.

Co-authored-by: GPT-5.5 <gpt-5.5@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf

theletterf commented Jun 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

@JoshMock @Mpdreamz I pushed a fix for the docs-build failure.

The broken build was caused by the generated CLI schema emitting a non-standard shortcuts field. Docs-builder turned those into alias pages for elastic es / elastic elasticsearch / elastic kb / elastic kibana, but those pages linked to /cli/stack/es/ and /cli/stack/kb/ in a way strict local-link validation rejected.

I removed shortcuts from the exported docs schema and regenerated docs/cli/schema.json. Runtime shortcuts are unchanged; they still come from the CLI argv rewrite/alias handling. Unless we need it for some reason, in which case we would have to fix docs-builder instead?

Verified locally:

  • npm test
  • npx eslint src/cli-schema.ts test/cli-schema.test.ts test/docs/search.test.ts
  • docs-builder build --path docs --path-prefix /elastic/cli/pull/406 --strict --skip-cross-links

@github-actions

github-actions Bot commented Jun 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🔍 Preview links for changed docs

@github-actions

github-actions Bot commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

✅ Elastic Docs Style Checker (Vale)

No issues found on modified lines!

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

@theletterf @cursoragent
fix(docs): clean up CLI reference navigation
50559e4 
Move install and configuration pages under the docs landing page and keep stack namespace files as CLI supplemental content only.

Co-authored-by: GPT-5.5 <gpt-5.5@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf

theletterf commented Jun 10, 2026

Copy link
Copy Markdown
Member Author

Pushed an additional docs cleanup commit to this branch:

  • Moved installation and configuration under the top-level docs landing page in docset.yml.
  • Removed the stack namespace supplemental pages from the explicit CLI TOC children, since docs-builder generates those entries from the schema.
  • Converted the stack/es and stack/kb supplemental files to start with ## Description so their metadata/frontmatter is not rendered as body content under the current docs-builder behavior.

I also opened the two upstream docs-builder PRs we discussed:

@theletterf @cursoragent
ci: retrigger checks
c075072 
Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @cursoragent
docs: override CLI reference title
6fa2cf9 
Co-authored-by: GPT-5.5 <gpt-5.5@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Anaethelion
Anaethelion approved these changes Jun 10, 2026
View reviewed changes

@Anaethelion Anaethelion left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

@JoshMock

JoshMock commented Jun 11, 2026

Copy link
Copy Markdown
Member

On this page, clicking "es" in the side column correctly goes to /cli/stack/es but in the main page body clicking "es" under the "Sub-namespaces" section goes to /cli/stack/es/index, which returns a 404 error.

@theletterf

theletterf commented Jun 11, 2026

Copy link
Copy Markdown
Member Author

@JoshMock Uh! Looking at it now.

theletterf and others added 3 commits June 11, 2026 09:29
@theletterf @claude
fix(docs): rename stack/es and stack/kb index.md to flat files
3f62267 
The docs-builder was generating Sub-namespace links as /cli/stack/es/index
instead of /cli/stack/es because the content files were named index.md
inside subdirectories. Renaming to flat .md files fixes the broken links.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf
ci: retrigger checks
3242c4e
@theletterf @claude
fix(docs): add frontmatter and nav entries for stack/es and stack/kb …
3c1cec7 
…pages

Flat .md files must have a title and be registered in the navigation.
Adds frontmatter (description, applies_to, type, navigation_title, H1)
and registers both files as children of the CLI schema toc entry.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
fix(docs): use hidden: instead of file: for stack/es and stack/kb fra…
c045449 
…gments

Hidden pages are registered in navigation (satisfying the docs-builder
requirement) but not shown in the sidebar.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf

theletterf commented Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

@JoshMock Should be good now, PTAL (can't merge on my own)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Anaethelion Anaethelion Anaethelion approved these changes

+1 more reviewer

@Mpdreamz Mpdreamz Mpdreamz approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@theletterf @JoshMock @Mpdreamz @Anaethelion