Skip to content

Use link targets that resolve for the aggregation cross-references - #65

Merged
guanzhousongmicrosoft merged 1 commit into
documentdb:mainfrom
GuanzhouSong:fix-reference-relative-links
Aug 3, 2026
Merged

Use link targets that resolve for the aggregation cross-references#65
guanzhousongmicrosoft merged 1 commit into
documentdb:mainfrom
GuanzhouSong:fix-reference-relative-links

Conversation

@GuanzhouSong

Copy link
Copy Markdown
Contributor

Summary

Seventeen cross-reference links across six pages point at relative .md paths, and every one of them 404s.

On $search, the link to $vectorSearch renders as:

href="./%24vectorsearch.md"

documentdb.io serves these pages with a trailing slash, so that resolves against the page's own directory and lands at /operators/aggregation/$search/%24vectorsearch.md — wrong depth and a leaked extension, the two failure modes #57 catalogued, in a single href. Confirmed 404 against the live site.

Affected

FileLinks
$search.md5
$project.md4
$vectorsearch.md3
$graphlookup.md2
$limit.md2
$meta.md1

They were introduced together: $vectorSearch, $project, $limit and $graphLookup arrived in #59, $search in #64 following the convention it found on the page beside it, and $meta links back the same way. None of them render, so those pages read as cross-linked while every cross-link is dead.

Fix

Rewritten to the absolute form the rest of the reference already uses:

https://documentdb.io/docs/reference/operators/aggregation/%24bucket/

That is what #57 settled on for exactly this reason — it does not depend on how the site resolves a relative path, and it survives a page moving between directories.

Verification

All 13 distinct targets were requested against the live site and return 200. No relative .md link remains anywhere in the repository:

$ grep -rn '](\.\{1,2\}/[^)]*\.md)' --include="*.md" . | wc -l
0

Related: this is the class of #38, which stays open for the wider .md-in-links question.

Seventeen links across six pages point at relative .md paths and every
one of them 404s. On $search the link to $vectorSearch renders as
href="./%24vectorsearch.md", which resolves against the page's own
directory - documentdb.io serves these with a trailing slash - and lands
at /operators/aggregation/$search/%24vectorsearch.md. Wrong depth and a
leaked extension, the two failure modes documentdb#57 catalogued, in the same
href.
They were introduced together. $vectorSearch, $project, $limit and
$graphLookup arrived in documentdb#59, $search in documentdb#64 following the convention it
found on the page next to it, and $meta links back to $vectorSearch the
same way. None of them render, so the pages read as cross-linked while
every cross-link is dead.
Rewritten to the absolute form the rest of the reference already uses -
https://documentdb.io/docs/reference/operators/aggregation/%24bucket/ -
which is what documentdb#57 settled on for exactly this reason: it does not depend
on how the site resolves a relative path, and it survives a page moving
between directories.
All thirteen distinct targets were requested against the live site and
return 200, and no relative .md link remains anywhere in the repository.

@guanzhousongmicrosoftguanzhousongmicrosoft 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.

Confirmed against the live site: the relative form 404s, all 13 absolute targets return 200, and no relative .md link remains in the repo.

Sign up for freeto 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

@GuanzhouSong@guanzhousongmicrosoft