docs: fix broken links, restore missing Development page, drop duplicate copies - #2370
Open
Suneha Bose (bosesuneha) wants to merge 2 commits into
Open
docs: fix broken links, restore missing Development page, drop duplicate copies#2370Suneha Bose (bosesuneha) wants to merge 2 commits into
Suneha Bose (bosesuneha) wants to merge 2 commits into
Conversation
…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)
Clarify the documentation policy regarding the release process and the changelog.
Suneha Bose (bosesuneha)
marked this pull request as ready for review
August 7, 2026 20:37
David Gamero (davidgamero)
approved these changes
Aug 13, 2026
David Gamero (davidgamero)
left a comment
David Gamero (davidgamero)
left a comment
Collaborator
There was a problem hiding this comment.
lgtm
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.
Summary
Fixes broken links and a blank published page in the docs, and removes three stale duplicate copies of pages that already live under
docs/book/src/.Changes
Missing Development page
SUMMARY.mdlinked to./development.md, which did not exist. mdBook'screate-missingdefault silently generated an empty stub, so the published Development section rendered as a bare heading. Adds the page and setscreate-missing = falseso this fails the build instead.Duplicate copies removed
Three files under
docs/were outdated forks of theirdocs/book/src/counterparts, anddocs/README.mdlinked only to the forks:docs/webview-development.mdbook/src/development/webview-development.mddocs/package-scripts.mdbook/src/development/development.mddocs/maintenance/README.mdbook/src/release/releasing.mddocs/README.mdis rewritten as an index intobook/..agents/skills/vscode-aks-tools-release-pr/SKILL.mdinstructed maintainers to mirror everyreleasing.mdedit intodocs/maintenance/README.md, which is why that fork stayed alive. Updated to namebook/src/as the single source of truth.Broken links and stale references
../package.jsonand../webview-ui/resolved outside the bookdev-webview/build-webvieware not real npm scripts (correct names:dev:webview,build:webview)webpack-uitypo forwebview-uiSUMMARY.mdnav labels disagreed with the pages' own titlesOther
bin/added to.gitignore.make -C docs/book buildwrites mdBook binaries to the repo root because the Makefile uses$(PWD)rather than$(CURDIR).Verification
mdbook buildexits 0 withcreate-missing = falselychee --offline --include-fragmentsoverdocs/**/*.md: 0 errors