fix(docs): correct relative link depths across docs site#2170
fix(docs): correct relative link depths across docs site#2170JasonTame wants to merge 3 commits into
Conversation
|
@microsoft-github-policy-service agree |
|
I recognise this is quite a wide change - I'm happy to break it up into smaller PRs if you prefer? I do think the real 'solution' is to avoid reference links entirely and use absolute links, that'll be easier to test (your existing link validator plugin will handle it) and easier to write. |
JasonTame
requested review from
danielmeppiel and
sergio-sisternes-epam
as code owners
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 1 | Pure docs link-depth fix; no runtime code, no architectural surface. Ship. |
| CLI Logging Expert | 0 | 0 | 0 | No CLI logging, output UX, or terminal-output contract surface touched. |
| DevX UX Expert | 0 | 0 | 1 | All link-depth corrections are directionally correct for Astro routing; no reader-intent regressions found. |
| Supply Chain Security Expert | 0 | 0 | 0 | No supply-chain surface touched, no security guidance misdirected, and no external URLs introduced. |
| OSS Growth Hacker | 0 | 0 | 1 | Fixing 462 broken links removes friction across the docs funnel. |
| Doc Writer | 0 | 0 | 1 | All changed lines are link-depth corrections; the build validates every internal link. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 2 follow-ups
- [DevX UX Expert] Replace raw filesystem-path link text in
common-errors.mdwith human-readable labels -- troubleshooting pages are high-intent; scannable labels reduce time-to-resolution. - [Doc Writer] Clarify why the PR's 462-link count differs from 416 changed lines -- some lines contain multiple links, so the counts are consistent, but a note could help future archaeology.
Architecture
classDiagram
direction LR
class AstroBuild {
<<BuildTool>>
+render(page.md) URL
}
class MarkdownPage {
<<Static>>
+relativeLinkDepth int
}
class StarlightLinksValidator {
<<StaticAnalysis>>
+validate(site) Report
}
note for MarkdownPage "PR scope: 54 docs pages; add one ../ per relative link"
AstroBuild ..> MarkdownPage : renders
StarlightLinksValidator ..> AstroBuild : validates output
class MarkdownPage:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
A["Author updates 54 docs pages"] --> B{"Each relative link gains one ../"}
B --> C["Correct link depth in docs source"]
C --> D["Astro renders page.md at /page/"]
D --> E["Starlight validator confirms internal links"]
E --> F["No runtime code touched"]
Recommendation
Ship now. Every panelist agrees, no correctness or security findings exist, and the docs build reports all internal links valid. The human-readable link-text polish in common-errors.md can ride in a future docs PR.
Full per-persona findings
Python Architect
- [nit] Design patterns: none apply to a docs-only link correction.
This is a straight-line mechanical correction across Markdown files. No classes, modules, runtime paths, or canonical-authority boundaries are touched.
CLI Logging Expert
No findings.
DevX UX Expert
- [nit]
common-errors.mduses filesystem paths as link text instead of human-readable labels atdocs/src/content/docs/troubleshooting/common-errors.md.
This pre-existing issue hurts scannability but is not introduced by this PR.
Suggested: Replace path-style link text with human-readable labels in a follow-up.
Supply Chain Security Expert
No findings.
OSS Growth Hacker
- [nit]
common-errors.mduses raw path strings as link display text atdocs/src/content/docs/troubleshooting/common-errors.md:24.
Human labels would improve high-intent troubleshooting navigation, but this is pre-existing.
Suggested: Use human-readable labels in a follow-up.
Auth Expert -- inactive
The PR touches only documentation files; no auth, token, credential, or authorization surface is affected.
Doc Writer
- [nit] The PR body's 462-link figure is not directly inferable from 416 changed lines because some lines contain multiple links.
This is cosmetic PR-description phrasing, not a shipped docs defect.
Test Coverage Expert -- inactive
Documentation-only PR -- no runtime code paths to defend.
Performance Expert -- inactive
The changed files are Starlight Markdown; no source, cache, transport, loop, or hot-path code is changed.
This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.
Replace raw path-shaped link text with readable labels so the corrected destinations are also scannable. Addresses the DevX UX panel follow-up. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | Docs-only link-depth corrections; no runtime architecture surface touched. Ship. |
| CLI Logging Expert | 0 | 0 | 0 | No CLI logging, terminal output, or diagnostic rendering surface touched. Ship. |
| DevX UX Expert | 0 | 0 | 0 | Link-depth fixes are correct and the link-label fold improves scannability. Ship. |
| Supply Chain Security Expert | 0 | 0 | 0 | No external URLs added and no security guidance redirected. Ship. |
| OSS Growth Hacker | 0 | 0 | 0 | No conversion-surface concerns remain after the fold. Ship. |
| Doc Writer | 0 | 0 | 0 | All destinations are valid, the build is clean, and no PR-caused doc issues remain. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Architecture
classDiagram
direction LR
class AstroBuild {
<<BuildPipeline>>
+collectPages() List~MarkdownPage~
+renderSite() void
}
class MarkdownPage {
<<ValueObject>>
+filePath str
+relativeLinks List~str~
+depth int
}
class StarlightLinksValidator {
<<Validator>>
+validateLinks(pages) List~BrokenLink~
+checkDepth(link, source) bool
}
AstroBuild *-- MarkdownPage : collects
AstroBuild ..> StarlightLinksValidator : invokes
StarlightLinksValidator ..> MarkdownPage : inspects
class MarkdownPage:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
A[54 docs pages with incorrect relative links] --> B[Correct link depth prefixes]
B --> C[Use readable labels for troubleshooting links]
C --> D[Astro build]
D --> E[Starlight link validation]
E --> F[All internal links valid]
Recommendation
Ship after the parent orchestrator resolves the current branch conflict. Zero panel findings remain, the docs build is green, and all specialists agree. No panel follow-ups remain.
Full per-persona findings
Python Architect
No findings.
CLI Logging Expert
No findings.
DevX UX Expert
No findings.
Supply Chain Security Expert
No findings.
OSS Growth Hacker
No findings.
Auth Expert -- inactive
All 54 touched files are documentation; no auth, token, credential, host-classification, or authorization surface changed.
Doc Writer
No findings.
Test Coverage Expert -- inactive
Documentation-only PR -- no runtime code paths to defend.
Performance Expert -- inactive
Documentation-only PR -- no performance-relevant source changed.
Folded in this run
- (panel) Replace raw path-shaped link display text in
common-errors.mdwith human-readable labels -- resolved in44252a99ed4688753184e755883d7ad32d95b8c7.
Deferred (out-of-scope follow-ups)
- (panel) Explain the difference between 462 link occurrences and 416 changed source lines in PR metadata -- scope boundary: the PR fixes shipped documentation links; review-metadata archaeology does not change user-facing behavior and the counts are already consistent.
Lint contract
uv run --extra dev ruff check src/ tests/ and uv run --extra dev ruff format --check src/ tests/ were silent. Pylint R0801 and the auth-signal boundary check also passed. npm run build completed with all internal links valid.
CI
Latest head 44252a9: GitHub reports license/cla successful, the only check currently emitted while the branch conflict remains. No CI fix iterations were needed.
Mergeability status
Captured from gh pr view 2170 --json mergeable,mergeStateStatus,statusCheckRollup after the push.
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #2170 | 44252a9 |
ship_now | 1 | 1 | 1 | 2 | green | CONFLICTING | DIRTY | needs rebase |
Convergence
1 outer iteration; 2 Copilot rounds with zero inline comments. Final panel stance: ship_now.
Ready for maintainer review after conflict resolution.
This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.
Description
Fixes 462 broken relative links across 54 doc pages. Astro renders
page.mdat/page/, adding an extra URL segment — so relative links need one more../than the filesystem suggests. Links using insufficient depth (e.g.../reference/foo/instead of../../reference/foo/) resolved to 404s.Fixes #2168
Type of change
Testing
npm run buildpasses withstarlight-links-validatorreporting all internal links validSpec conformance (OpenAPM v0.1)