Skip to content

Commit 04ce3ad

Browse files
Resolve Markdown document links from source paths
Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent d64aa6c commit 04ce3ad

8 files changed

Lines changed: 129 additions & 12 deletions

File tree

‎app/components/Markdown.tsx‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,14 @@ import { useMemo } from 'react';
66
import type { ReactElement } from 'react';
77
import Code from './Code';
88
import { kebabCase } from 'change-case';
9+
import { resolveMarkdownLink } from '../lib/markdownLinks';
910

10-
export default function Markdown({ content }: { content: string }) {
11+
interface MarkdownProps {
12+
content: string;
13+
sourcePath: string;
14+
}
15+
16+
export default function Markdown({ content, sourcePath }: MarkdownProps) {
1117
const processedContent = useMemo(() => {
1218
// Split content by H2 headings to group sections
1319
const sections = content.split(/^## /gm);
@@ -22,7 +28,7 @@ export default function Markdown({ content }: { content: string }) {
2228
<div key={`intro-${index}`} className="mb-8">
2329
<ReactMarkdown
2430
remarkPlugins={[remarkGfm]}
25-
components={getMarkdownComponents()}
31+
components={getMarkdownComponents(sourcePath)}
2632
>
2733
{section}
2834
</ReactMarkdown>
@@ -42,7 +48,7 @@ export default function Markdown({ content }: { content: string }) {
4248
</h2>
4349
<ReactMarkdown
4450
remarkPlugins={[remarkGfm]}
45-
components={getMarkdownComponents()}
51+
components={getMarkdownComponents(sourcePath)}
4652
>
4753
{sectionContent}
4854
</ReactMarkdown>
@@ -52,12 +58,12 @@ export default function Markdown({ content }: { content: string }) {
5258
});
5359

5460
return elements;
55-
}, [content]);
61+
}, [content, sourcePath]);
5662

5763
return <div className="space-y-8">{processedContent}</div>;
5864
}
5965

60-
function getMarkdownComponents() {
66+
function getMarkdownComponents(sourcePath: string) {
6167
return {
6268
// H1 headings (main page title from Markdown content)
6369
h1: ({ children, ...props }: any) => (
@@ -247,10 +253,11 @@ function getMarkdownComponents() {
247253
// Links: only external links open in a new tab; internal links (/docs/...,
248254
// /samples, #anchors) navigate in place
249255
a: ({ children, href, ...props }: any) => {
250-
const isExternal = /^https?:\/\//i.test(href ?? '');
256+
const resolvedHref = resolveMarkdownLink(href, sourcePath);
257+
const isExternal = /^https?:\/\//i.test(resolvedHref ?? '');
251258
return (
252259
<a
253-
href={href}
260+
href={resolvedHref}
254261
className="text-blue-400 hover:text-blue-300 transition-colors"
255262
{...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
256263
{...props}

‎app/docs/[section]/[[...slug]]/page.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -322,7 +322,10 @@ export default async function ArticlePage({ params }: PageProps) {
322322
)}
323323

324324
{/* Markdown Content */}
325-
<Markdown content={content} />
325+
<Markdown
326+
content={content}
327+
sourcePath={`/docs/${section}/${file}.md`}
328+
/>
326329
</div>
327330
</div>
328331
</div>

‎app/docs/reference/[type]/[category]/[name]/page.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,10 @@ export default async function ReferencePage({ params }: { params: Promise<{ type
4747
<Breadcrumb type={type} category={category} name={pageTitle} />
4848

4949
{/* Markdown Content */}
50-
<Markdown content={data.content} />
50+
<Markdown
51+
content={data.content}
52+
sourcePath={`/docs/reference/${type}/${category}/${decodedName}.md`}
53+
/>
5154
</article>
5255
);
5356
}

‎app/docs/reference/[type]/[category]/page.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,10 @@ export default async function CommandReferencePage({ params }: { params: Promise
4545
<div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
4646
{description && (
4747
<div className="text-gray-400 text-lg mb-6">
48-
<Markdown content={description} />
48+
<Markdown
49+
content={description}
50+
sourcePath={`/docs/reference/${type}/${category}/_metadata.description.md`}
51+
/>
4952
</div>
5053
)}
5154
</div>

‎app/docs/reference/[type]/page.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,10 @@ export default async function CommandReferencePage({ params }: { params: Promise
4444
<div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
4545
{description && (
4646
<div className="text-gray-400 text-lg mb-6">
47-
<Markdown content={description} />
47+
<Markdown
48+
content={description}
49+
sourcePath={`/docs/reference/${type}/_metadata.description.md`}
50+
/>
4851
</div>
4952
)}
5053
</div>

‎app/docs/reference/page.tsx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,10 @@ export default function Home() {
3030
<div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
3131
{description && (
3232
<div className="text-gray-400 text-lg mb-6">
33-
<Markdown content={description} />
33+
<Markdown
34+
content={description}
35+
sourcePath="/docs/reference/_metadata.description.md"
36+
/>
3437
</div>
3538
)}
3639
</div>

‎app/lib/markdownLinks.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
const markdownOrigin = 'https://documentdb.invalid';
2+
3+
export function resolveMarkdownLink(
4+
href: string | undefined,
5+
sourcePath: string,
6+
): string | undefined {
7+
if (!href) {
8+
return href;
9+
}
10+
11+
if (/^[a-z][a-z\d+.-]*:/i.test(href) || href.startsWith('//')) {
12+
return href;
13+
}
14+
15+
const hrefPath = href.split(/[?#]/, 1)[0];
16+
if (!hrefPath.toLowerCase().endsWith('.md')) {
17+
return href;
18+
}
19+
20+
const normalizedSourcePath = sourcePath.startsWith('/')
21+
? sourcePath
22+
: `/${sourcePath}`;
23+
// URL applies the same dot-segment rules as a browser without coupling the
24+
// result to the page URL that happens to render this source file.
25+
const target = new URL(href, new URL(normalizedSourcePath, markdownOrigin));
26+
27+
if (target.pathname.toLowerCase().endsWith('/index.md')) {
28+
target.pathname = target.pathname.slice(0, -'index.md'.length);
29+
} else {
30+
target.pathname = `${target.pathname.slice(0, -'.md'.length)}/`;
31+
}
32+
33+
return `${target.pathname}${target.search}${target.hash}`;
34+
}

‎tests/markdownLinks.test.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import { describe, expect, it } from 'vitest';
2+
import { resolveMarkdownLink } from '../app/lib/markdownLinks';
3+
4+
describe('resolveMarkdownLink', () => {
5+
it('maps a sibling Markdown file to its published article route', () => {
6+
expect(
7+
resolveMarkdownLink(
8+
'functions.md',
9+
'/docs/postgres-api/index.md',
10+
),
11+
).toBe('/docs/postgres-api/functions/');
12+
});
13+
14+
it('resolves encoded operator filenames from the source directory', () => {
15+
expect(
16+
resolveMarkdownLink(
17+
'./%24bucket.md',
18+
'/docs/reference/operators/aggregation/%24bucketauto.md',
19+
),
20+
).toBe('/docs/reference/operators/aggregation/%24bucket/');
21+
});
22+
23+
it('normalizes parent-directory references before publishing the route', () => {
24+
expect(
25+
resolveMarkdownLink(
26+
'../aggregation/aggregate.md',
27+
'/docs/reference/commands/query-and-write/getMore.md',
28+
),
29+
).toBe('/docs/reference/commands/aggregation/aggregate/');
30+
});
31+
32+
it('collapses index files to their directory route', () => {
33+
expect(
34+
resolveMarkdownLink(
35+
'../index.md#quick-start',
36+
'/docs/getting-started/guides/python.md',
37+
),
38+
).toBe('/docs/getting-started/#quick-start');
39+
});
40+
41+
it('preserves query strings and fragments', () => {
42+
expect(
43+
resolveMarkdownLink(
44+
'python-setup.md?view=full#connect',
45+
'/docs/getting-started/index.md',
46+
),
47+
).toBe('/docs/getting-started/python-setup/?view=full#connect');
48+
});
49+
50+
it.each([
51+
'https://example.com/readme.md',
52+
'//example.com/readme.md',
53+
'/docs/reference/',
54+
'#examples',
55+
'mailto:guide.md',
56+
])('leaves non-source-document link %s unchanged', (href) => {
57+
expect(
58+
resolveMarkdownLink(href, '/docs/getting-started/index.md'),
59+
).toBe(href);
60+
});
61+
});

0 commit comments

Comments
 (0)