Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"@fontsource/teko": "^5.1.1",
"@tailwindcss/vite": "^4.1.4",
"astro": "^7.0.0",
"mdast-util-to-markdown": "^2.1.2",
"sharp": "^0.35.0",
"starlight-github-alerts": "^0.5.0",
"starlight-image-zoom": "^0.16.0",
Expand Down
32 changes: 31 additions & 1 deletion src/build/integration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,13 @@ import {
rmSync,
writeFileSync,
} from 'fs';
import { basename, dirname, join } from 'path';
import { basename, dirname, join, resolve } from 'path';
import { fileURLToPath } from 'url';
import { discoverAllVersions, minorKey, parseOverrides, readProductsJson } from './versions';
import { computeSlugRename, toTitleCase } from './dirRename';
import { rewriteLinks } from './linkRewrite';
import { createRawLinkRewriter } from './rawLinkRewrite';
import { latestProductVersion } from '../versionUtils';
import { VERSION_SLUG_RE } from './cleanupDirs';
import {
bustAstroCache,
Expand Down Expand Up @@ -343,6 +345,34 @@ export async function main(): Promise<void> {
}
}

// Normalize copied source too: raw LLM exports bypass the Remark pipeline.
const sections = (config: DocsConfig) => config.sidebarOrder.map(
entry => typeof entry === 'string' ? entry : entry.dir,
);
const versionsByRepo = Object.fromEntries(Object.values(versions).map(v => [v.repo, v]));
const rewriteRaw = createRawLinkRewriter({
srcDir: resolve(TARGET_DIR),
products: [...configCache.entries()].map(([repoName, config]) => {
const channel = productChannels.get(repoName);
const latest = latestProductVersion({ ...config, latestSource: channel }, versionsByRepo);
return {
contentDir: config.contentDir,
channel,
sections: sections(config),
latestPrefix: `/${config.contentDir}${channel ? `/${latest?.slug ?? channel}` : ''}`,
versionedSections: Object.fromEntries(versions[config.repo].versions.flatMap(version => {
const configPath = join(CONFIG_DIR, `${repoName}.${version.slug}.json`);
return existsSync(configPath) ? [[version.slug, sections(readDocsConfig(configPath))]] : [];
})),
};
}),
});
for (const file of collectMarkdownFiles(TARGET_DIR)) {
const original = readFileSync(file, 'utf8');
const rewritten = await rewriteRaw(original, resolve(file));
if (rewritten !== original) writeFileSync(file, rewritten);
}

// ------------------------------------------------------------------
// Step 9: Bust Astro cache
// ------------------------------------------------------------------
Expand Down
41 changes: 41 additions & 0 deletions src/build/rawLinkRewrite.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import { expect, it } from 'vitest';
import { parseFrontmatter } from '@astrojs/markdown-remark';
import { createRawLinkRewriter } from './rawLinkRewrite';

const options = {
srcDir: '/docs',
products: [{ contentDir: 'core', sections: ['concepts'], latestPrefix: '/core/v1-16' }],
};

it.each(['', '\n', '\uFEFF'])('retains frontmatter with prefix %j while rewriting links', async (prefix) => {
const rewrite = createRawLinkRewriter(options);
const source = '---\ntitle: Guide\n---\n\n[Guide](/concepts/guide/#intro)\n\n[guide]: /concepts/guide/\n\n`[Example](/concepts/example/)`';
const result = await rewrite(prefix + source, '/docs/core/v1-16/index.md');
expect(result.startsWith(prefix + '---\ntitle: Guide\n---')).toBe(true);
expect(parseFrontmatter(result).frontmatter.title).toBe('Guide');
expect(result).toContain('[Guide](/core/v1-16/concepts/guide/#intro)');
expect(result).toContain('[guide]: /core/v1-16/concepts/guide/');
expect(result).toContain('`[Example](/concepts/example/)`');
expect(await rewrite(result, '/docs/core/v1-16/index.md')).toBe(result);
});

it('rewrites nested MDX links without rendering LikeC4 or changing fenced examples', async () => {
const rewrite = createRawLinkRewriter(options);
const source = `import LikeC4View from '@components/LikeC4View.astro';

<CardGrid><Card title="Setup">
[Guide](/concepts/guide/)
<LinkCard href="/concepts/guide/" />
</Card></CardGrid>
<LikeC4View viewId="index" />

\`\`\`mdx
<LinkCard href="/concepts/example/" />
\`\`\`
`;
const result = await rewrite(source, '/docs/core/v1-16/index.mdx');
expect(result).toContain('[Guide](/core/v1-16/concepts/guide/)');
expect(result).toContain('<LinkCard href="/core/v1-16/concepts/guide/" />');
expect(result).toContain('<LikeC4View viewId="index" />');
expect(result).toContain('```mdx\n<LinkCard href="/concepts/example/" />\n```');
});
36 changes: 36 additions & 0 deletions src/build/rawLinkRewrite.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import { createMarkdownProcessor, parseFrontmatter, unified, type RemarkPlugins } from '@astrojs/markdown-remark';
import { toMarkdown, type Options } from 'mdast-util-to-markdown';
import { pathToFileURL } from 'node:url';
import type { Root } from 'mdast';
import { remarkLinkRewrite, type LinkRewriteOptions } from '../plugins/remark-link-rewrite';

/** Apply the site's link rules to raw Markdown/MDX without rendering components. */
export function createRawLinkRewriter(options: LinkRewriteOptions) {
return async (source: string, filePath: string): Promise<string> => {
const { content } = parseFrontmatter(source, { frontmatter: 'empty-with-spaces' });
// Astro masks the header in place; the last changed character marks its end.
let headerEnd = source.length;
while (headerEnd > 0 && source[headerEnd - 1] === content[headerEnd - 1]) headerEnd--;
let rewritten = '';
const remarkPlugins: RemarkPlugins = [
[remarkLinkRewrite, options],
function serialize(this: { data(key: string): Options['extensions'] }) {
const extensions = this.data('toMarkdownExtensions');
return (tree: Root) => {
rewritten = toMarkdown(tree, { extensions });
};
},
];
if (filePath.endsWith('.mdx')) {
const mdx = await unified({ remarkPlugins, smartypants: false }).createMdxRenderer!(
{ syntaxHighlight: false }, { optimize: false },
);
await mdx.process(content, filePath, {});
} else {
const markdown = await createMarkdownProcessor({ syntaxHighlight: false, smartypants: false, remarkPlugins });
await markdown.render(content, { fileURL: pathToFileURL(filePath) });
}
// Keep frontmatter unchanged; only the document body is serialized.
return source.slice(0, headerEnd) + '\n\n' + rewritten;
};
}
6 changes: 3 additions & 3 deletions src/plugins/remark-link-rewrite.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ interface ProductConfig {
latestPrefix: string;
}

interface Options {
export interface LinkRewriteOptions {
products: ProductConfig[];
srcDir: string;
}
Expand All @@ -28,7 +28,7 @@ interface Options {
* @param options.products - Per-product section lists and optional version overrides
* @param options.srcDir - Absolute path to src/content/docs/
*/
export function remarkLinkRewrite(options: Options) {
export function remarkLinkRewrite(options: LinkRewriteOptions) {
const { products, srcDir } = options;

// Pre-build Sets for all section lookups so we don't re-create them per file.
Expand Down Expand Up @@ -125,7 +125,7 @@ export function remarkLinkRewrite(options: Options) {
: `/${contentDir}`;

// Rewrite markdown links: [text](/section/...) → [text](/core/section/...)
visit(tree, 'link', (node) => {
visit(tree, ['link', 'definition'], (node: any) => {
node.url = rewriteInternalUrl(node.url, prefix, sections, contentDir);
});

Expand Down
Loading