Skip to content

Fix broken links in src/ docs#7

Merged
crutkas merged 1 commit into
microsoft:mainfrom
crutkas:fix/broken-doc-links
May 23, 2026
Merged

Fix broken links in src/ docs#7
crutkas merged 1 commit into
microsoft:mainfrom
crutkas:fix/broken-doc-links

Conversation

@crutkas

@crutkas crutkas commented May 23, 2026

Copy link
Copy Markdown
Member

Summary

Fixes five broken cross-references in src/ documentation, found by a
static markdown link scan of the repo. The top-level README.md and
the per-flow READMEs (Windows Dev Config/README.md, Wsl Comfort/readme.md)
were already clean — every broken link is inside src/.

What was broken

File Line Old target Failure
src/docs/development.md 4 ../README.md Resolves to src/README.md (doesn't exist).
src/future/cmdpal/README.md 5 ../manifest.yml Resolves to src/future/manifest.yml (doesn't exist; manifest is at src/manifest.yml).
src/future/cmdpal/README.md 15 ../README.md#prerequisites-windows Resolves to src/future/README.md (doesn't exist). The #prerequisites-windows anchor also only exists in src/docs/development.md, not in the top-level README.
src/future/cmdpal/README.md 19 ../scripts/windows/_common/assert-winget-configure.ps1 Stale path; the file lives at src/Workloads/_common/assert-winget-configure.ps1 in this repo.
src/future/cmdpal/README.md 107 https://learn.microsoft.com/windows/powertoys/command-palette/ 404. The overview page is at /command-palette/overview.

What this PR does

Three of the four relative-link fixes are pure path corrections (one
more .. segment to escape src/'s subdirectories properly).

Two also adjust the link text so it matches the destination:

  • The Prerequisites (Windows) cross-reference originally said "top-level
    README's Prerequisites section" but the anchor #prerequisites-windows
    only exists in src/docs/development.md's "Prerequisites (Windows)"
    header. Repointed to src/docs/development.md#prerequisites-windows
    and changed the link text to "the developer guide's Prerequisites (Windows)" so the description matches what readers land on.
  • The assert-winget-configure.ps1 reference originally displayed the
    path scripts/windows/_common/assert-winget-configure.ps1 and pointed
    at the same. Updated both the displayed path and the target to
    Workloads/_common/assert-winget-configure.ps1, the current layout.

The single absolute-URL fix appends /overview to the MS Learn URL
(verified 200).

Verification

Re-ran the same link scan on the patched tree: 0 broken out of 182
links. Diff is +7 / -7 across two files.

src/docs/development.md     |  2 +-
src/future/cmdpal/README.md | 12 ++++++------

Five broken relative/absolute links found by a static markdown link scan
of the repo. All are inside src/; the top-level README and per-flow
READMEs were already clean.

- src/docs/development.md: top-level README link was '../README.md',
  which resolves to 'src/README.md' (doesn't exist). Bump to
  '../../README.md' so it reaches the repo root.

- src/future/cmdpal/README.md, four fixes:
  1. manifest.yml link was '../manifest.yml' (-> 'src/future/manifest.yml');
     fix to '../../manifest.yml'.
  2. Prerequisites cross-link pointed at '../README.md#prerequisites-windows',
     which resolves to 'src/future/README.md' (doesn't exist) and the
     '#prerequisites-windows' anchor doesn't exist in the top-level README
     either - it only exists in src/docs/development.md. Repoint to
     '../../docs/development.md#prerequisites-windows' and adjust the link
     text from 'top-level README' to 'developer guide' so the description
     matches the destination.
  3. assert-winget-configure.ps1 link pointed at
     '../scripts/windows/_common/assert-winget-configure.ps1', a leftover
     from an older kebab-case layout. The file lives at
     'src/Workloads/_common/assert-winget-configure.ps1' in this repo.
     Repoint and update the displayed path.
  4. The 'ConfirmableCommand' reference URL
     https://learn.microsoft.com/windows/powertoys/command-palette/ is a
     404; the actual overview page is at
     https://learn.microsoft.com/windows/powertoys/command-palette/overview
     (verified 200). Append '/overview'.

Verified by re-running the same link scan on the patched tree: 0 broken
out of 182 links.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@crutkas crutkas merged commit f72a9fd into microsoft:main May 23, 2026
11 checks passed
crutkas added a commit that referenced this pull request May 23, 2026
Renames the two outlier spaced directories in lockstep across the
signed top-level tree and the unsigned src/ tree:

    Windows Dev Config/      -> windows-dev-config/
    Wsl Comfort/             -> wsl-comfort/
    src/Windows Dev Config/  -> src/windows-dev-config/
    src/Wsl Comfort/         -> src/wsl-comfort/

The sibling Workloads/<lang>/ directories already use kebab/lowercase
(dotnet/, winforms/, etc.); this aligns the two outliers with that
convention. The friendly product names "Windows Dev Config" and "WSL
Comfort" remain in section headings and prose - only the four parent
directory names change. Filenames inside those directories
(dev-config.winget, install.ps1, README.md, readme.md,
comfort-shell-bootstrap.sh) are unchanged.

Why
---

Every documented command and cross-link in the repo had to defend
against the space:

    winget configure -f ".\Windows Dev Config\dev-config.winget" `
        --accept-configuration-agreements --disable-interactivity

    & ".\Wsl Comfort\install.ps1"

That second example needs the `&` call operator only because the path
is a quoted string literal - `.\Wsl Comfort\install.ps1` without quotes
is a PowerShell syntax error, and `& .\Wsl Comfort\install.ps1` (no
surrounding quotes) calls `.\Wsl` with `Comfort\install.ps1` as an
argument. Tab completion auto-quotes the path
(`.\"Windows Dev Config"\`), producing a different syntactic shape
than what the docs show. Every markdown cross-link had to URL-encode
the space (`%20`). None of these affect the sibling Workloads/<lang>/
flows, because none of those have a space.

Post-rename the same commands are:

    winget configure -f .\windows-dev-config\dev-config.winget `
        --accept-configuration-agreements --disable-interactivity

    .\wsl-comfort\install.ps1

No quoting, no `&`, no `%20`.

What changed
------------

* git mv across the four directories. File blobs are unchanged; the
  signed top-level install.ps1's still carry their Authenticode
  signature block (`# SIG # Begin signature block` ... `# SIG # End
  signature block`), the src/ copies remain unsigned. Verified
  on-disk after the rename.
* README.md: five command/link references updated; the WSL Comfort
  invocation simplifies from `& ".\Wsl Comfort\install.ps1"` to
  `.\wsl-comfort\install.ps1`.
* src/docs/development.md: two table links and two repo-layout-tree
  lines.
* src/manifest.yml: `install` and `configuration` paths for the
  manual-test flows (`comfort-shell`, `calm-os`). The pre-existing
  asymmetry where these two flows declare paths without a `src/`
  prefix (the automated workloads use `src/Workloads/...`) is
  preserved - that is a separate cleanup not in scope here.
* .pipelines/OneBranch.SignAndPackage.yml: the CopyFiles@2 `Contents`
  glob lines for the signed release artifact.
* No script or .cs file inside the moved directories references its
  parent dir by name. PowerShell scripts use $PSScriptRoot;
  comfort-shell-bootstrap.sh is self-relative. Verified by grep.

Inside the repo nothing else mentions the old names as a path. The
only remaining instances of the strings "Windows Dev Config" and "WSL
Comfort" are in human prose - the README's section heading, the
feature description paragraphs, and a Troubleshooting bullet that
names the product, not the path.

External impact (out of scope of the patch, called out for awareness)
---------------------------------------------------------------------

GitHub does not provide URL redirects for renamed paths. Any bookmark,
blog post, Slack/Teams link, or wiki page pointing at
github.com/microsoft/WindowsDeveloperConfig/.../Windows%20Dev%20Config/
or .../Wsl%20Comfort/ will start returning 404 once this merges. The
proposal weighed leaving a single-file MOVED.md placeholder at each
old path; the placeholder approach was rejected because it would
re-introduce the spaced directory names just to host a redirect note,
defeating the goal of the rename and re-creating the tab-completion
ambiguity. The mitigation is a release announcement and a heads-up to
any in-repo PR authors to rebase.

Verification
------------

* Re-ran the same static markdown link scan that was used to find the
  five broken links fixed in #7: 0 broken out of 182 links on the
  renamed tree.
* grep on the working tree for the patterns `Windows Dev Config/`,
  `Wsl Comfort/`, `Windows%20Dev%20Config`, `Wsl%20Comfort`,
  `".\Windows Dev Config`, `".\Wsl Comfort` returns no matches.
* git diff --stat confirms 16 files changed, 14 insertions(+), 14
  deletions(-) - all inside the four manifest+docs+pipeline files
  above. Body bytes of the moved scripts are unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@crutkas crutkas deleted the fix/broken-doc-links branch May 23, 2026 06:59
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.

2 participants