Skip to content

docs: correct menu paths, add generated reference, fix navigation - #2372

Open
Suneha Bose (bosesuneha) wants to merge 7 commits into
Azure:mainfrom
bosesuneha:docs/content-corrections
Open

docs: correct menu paths, add generated reference, fix navigation#2372
Suneha Bose (bosesuneha) wants to merge 7 commits into
Azure:mainfrom
bosesuneha:docs/content-corrections

Conversation

@bosesuneha

@bosesuneha Suneha Bose (bosesuneha) commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

PR 2 of 3. Stacked on #2370, so it currently shows that PR's commits too. Review the three commits listed below; they need different levels of scrutiny.

Depends on #2371 for the generator.

1. Generated reference and navigation

Adds a Reference section generated from package.json by scripts/generate-docs-reference.js, carrying a DO NOT EDIT header: commands with their menu placement, settings, and pinned versions. Menu placement is not derivable by hand, with 66 commands across two menu modes nested up to four levels.

SUMMARY.md listed show-properties-azureportal-start-stop.md four times under four labels and inspektor-gadget.md twice, so three sidebar entries led to a page that did not match the label clicked. Collapsed to one each. No URLs change.

features.md was a stale 2.1.0 release spotlight with 20 generically captioned screenshots, linking to 2 of its 25 feature pages. Rewritten as an index.

2. Menu path corrections (needs the most review)

aks.simplifiedMenuStructure has defaulted to true since #2168, grouping cluster commands under Develop & Deploy, Troubleshoot & Diagnose, and Manage Cluster. The guides still described the classic flat menu, so readers were told to look for items that are now one level down.

Paths come from the generated reference, not from reading the UI, and are written as Right-click your AKS cluster > Submenu > Command so docs-check can validate them.

Beyond the missing group level:

Page Was Actually
aks-compare-cluster cluster node subscription node
manage-cluster-operations "Managed Cluster Operations" classic label; default is "Manage Cluster"
kaito-* "Deploy an LLM with KAITO" "Deploy a LLM with KAITO"
container-assist-integration AKS: Run Container Assist (Preview) has no menu contribution; replaced with the three real commands
inspektor-gadget "moved to the main context menu" describes the classic layout, now backwards

"Abort Last Operation" was listed as a cluster operation. It is a webview action in ClusterPropertiesPanel.ts, not a command, and there are two of them. simplified-menu-structure.md advised keeping the default false while stating above that it was true.

merge-save-kubeconfig.md is untouched: those commands belong to ms-kubernetes-tools.vscode-kubernetes-tools, which is a separate correction.

3. Heading levels (mechanical, skim it)

Only the number of leading # changes. Heading text is untouched, so every anchor still resolves. 17 pages had a broken hierarchy: 12 jumped from # straight to ###, 5 had no top-level heading.

Verification

docs:check 0 errors, docs:reference:check up to date, mdbook build clean, lychee --offline --include-fragments 0 errors.

Remaining warnings are tracked for PR 3: 21 undocumented commands, 14 orphaned images. Five of those orphans come from the features.md rewrite and are classic-menu screenshots predating the menu change, so they were stale regardless.

4. Command Palette shows "AKS: AKS:" (added)

aks.kickstart.launchExperience and aks.kickstartCluster set both category: "AKS" and an AKS: prefix in their title. VS Code composes the palette entry as category: title, so both rendered as:

AKS: AKS: Launch Kickstart Agent
AKS: AKS: Configure Kickstart Cluster

The prefix belongs in exactly one place; dropped it from the titles. The rendered palette text is now what the docs already claimed it was.

generate-docs-reference.js already flags this class of problem (title repeats its category), so the fix is verified by the generator going quiet rather than by inspection. Regenerated reference/commands.md in the same commit so generated output cannot disagree with package.json.

No localized package.nls.*.json files exist and l10n/bundle.l10n.json does not carry these strings, so no translations are affected.

Two related findings the generator reports were left alone as product decisions:

  • aks.aksKaitoGenerateYaml and aks.aksKaitoCreateCRD are both titled Create KAITO Workspace and both palette-visible.
  • 41 palette-visible commands have neither a category nor a prefix (Storage, Best Practices, Node Health, Delete Cluster), so they appear unattributed in the global palette.

5. create-gh-workflow.md removed (added)

The page described the retired actions/starter-workflows templates. The live command aks.draftWorkflow scaffolds via Draft and is documented in draft-integration.md. Removed from SUMMARY.md and the feature index.

6. Rebased onto current main

The branch was based on a commit predating #2353, which renamed aks.draftArgoCDDeployment to AKS: Create Argo CD Application. The committed reference still carried the old name and would have failed docs:reference:check once #2371 lands. Rebased and regenerated.

README.md re-listed all 25 feature pages by hand — a third copy after SUMMARY.md and features.md, and already drifted: four entries pointed at the same page under different labels, and the Container Assist sub-pages and Copilot plugin page were missing. Replaced with pointers to the feature index and the generated reference.

This was referenced Aug 6, 2026
Open
Merged
@bosesuneha
Suneha Bose (bosesuneha) marked this pull request as ready for review August 12, 2026 00:23
@bosesuneha
docs: fix broken links, restore missing Development page, drop duplic…
a4c2edc 
…ate copies

The published Development section rendered as a bare heading because
SUMMARY.md linked to ./development.md, which did not exist. mdBook's
create-missing default silently generated an empty stub instead of failing,
so this went unnoticed. Add the page and set create-missing = false.

Three pages under docs/ were stale forks of their docs/book/src/
counterparts, and docs/README.md linked only to the forks:

  docs/webview-development.md  missing the Custom UI Elements section
  docs/package-scripts.md      missing the Local VSIX Sharing section
  docs/maintenance/README.md   last updated 2021; missing the pinned
                               third-party versions section entirely

Delete them and rewrite docs/README.md as an index into book/.
The release skill instructed maintainers to mirror releasing.md into
docs/maintenance/README.md, which is why that fork stayed alive; update it
to name book/src/ as the single source of truth.

Also fixed:
- ../package.json and ../webview-ui/ links resolved outside the book
- dev-webview / build-webview are not real npm scripts (dev:webview,
  build:webview)
- webpack-ui typo for webview-ui
- SUMMARY.md nav labels disagreed with the pages' own titles
- bin/ ignored; make -C docs/book build writes mdBook binaries to the repo
  root because the Makefile uses $(PWD) rather than $(CURDIR)
@bosesuneha
docs: add generated reference section and fix feature navigation
ebb9f49 
Adds reference/ pages generated from package.json by
scripts/generate-docs-reference.js, carrying a DO NOT EDIT header: commands
with their menu placement, settings, and pinned versions.

SUMMARY.md listed show-properties-azureportal-start-stop.md four times and
inspektor-gadget.md twice, so three sidebar entries led to a page that did not
match the label clicked. Collapsed to one entry each; no URLs change.

features.md was a stale 2.1.0 release spotlight that linked to 2 of its 25
feature pages. Rewritten as an index. This orphans 5 classic-menu screenshots,
removed in a later PR.
@bosesuneha
docs: correct cluster menu paths in feature guides
502cbcf 
aks.simplifiedMenuStructure has defaulted to true since Azure#2168, grouping cluster
commands under Develop & Deploy, Troubleshoot & Diagnose, and Manage Cluster.
The guides still described the classic flat menu, so readers were told to look
for items that are now one level down.

Paths come from the generated menu reference, not from reading the UI, and are
written as "Right-click your AKS cluster > Submenu > Command" so docs-check can
validate them. Guides describe the default menu; the classic layout is covered
once, in simplified-menu-structure.md.

Also corrected:

- aks-compare-cluster is on the subscription node, not the cluster node
- "Managed Cluster Operations" is the classic label; the default is
  "Manage Cluster"
- the KAITO submenu is "Deploy a LLM with KAITO", not "an LLM"
- container-assist pointed at AKS: Run Container Assist (Preview), which has no
  menu contribution; replaced with the three real commands
- inspektor-gadget claimed the command had moved to the main context menu,
  which described the classic layout and was backwards
- "Abort Last Operation" is a webview action in ClusterPropertiesPanel.ts, not
  a command, so it is no longer listed as a menu operation
- simplified-menu-structure.md advised keeping the default false while stating
  above that it was true

merge-save-kubeconfig.md is left alone: those commands belong to
ms-kubernetes-tools.vscode-kubernetes-tools.
@bosesuneha
docs: normalise heading levels
3eb3edb 
Mechanical. Only the number of leading '#' changes; heading text is untouched,
so every anchor still resolves.

17 pages had a broken hierarchy: 12 jumped from '#' straight to '###', and 5
had no top-level heading at all. Each file's levels were remapped to a
contiguous sequence starting at 1, and where that left more than one h1 the
later ones were demoted so each page has a single title.

Sidebar labels come from SUMMARY.md so navigation was unaffected, but skipped
levels are a problem for screen readers.
@bosesuneha
docs: fix doubled AKS prefix in palette, drop deprecated workflow page
8a22c01 
Two commands set both `category: "AKS"` and an `AKS: ` prefix in their
title, so VS Code rendered them as "AKS: AKS: Launch Kickstart Agent"
and "AKS: AKS: Configure Kickstart Cluster" in the Command Palette.
VS Code composes the palette entry as `category: title`, so the prefix
belongs in exactly one of the two. Dropped it from the titles.

No localized `package.nls.*.json` files exist and `l10n/bundle.l10n.json`
does not carry these strings, so no translations are affected. The
rendered palette text is unchanged from what the docs already describe.

`generate-docs-reference.js` already reports this class of problem
("title repeats its category"); that finding is now clear. Regenerated
`reference/commands.md` in the same commit so the generated output
cannot disagree with `package.json`.

Removed `create-gh-workflow.md`. It described the retired
`actions/starter-workflows` templates, while the live command
(`aks.draftWorkflow`) scaffolds via Draft and is documented in
`draft-integration.md`.

`README.md` re-listed all 25 feature pages by hand, a third copy after
SUMMARY.md and features.md. It had drifted: four entries pointed at the
same page under different labels, and the Container Assist sub-pages and
Copilot plugin page were missing. Replaced with pointers to the Features
index and the generated Reference.
@bosesuneha
docs: regenerate reference after Argo CD command rename
7bab4bc 
Rebased onto main, which renamed aks.draftArgoCDDeployment to
"AKS: Create Argo CD Application" in Azure#2353. Regenerated so the
committed reference matches package.json; otherwise
docs:reference:check would fail once Azure#2371 lands.
@bosesuneha
Merge branch 'main' into docs/content-corrections
88961c4 
Signed-off-by: Suneha Bose <123775811+bosesuneha@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bosesuneha