fix(docs): address documentation site review

scripts/project-doc-site.spec.ts

@@ -4,7 +4,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { DocsPage } from '../website/docs.ts'
+import { docsPages, type DocsPage } from '../website/docs.ts'
 import { addProjectionFrontmatter, rewriteMarkdown } from './project-doc-site.ts'
 
 const roots: string[] = []
@@ -25,8 +25,10 @@ function fixture(): { root: string; pages: DocsPage[] } {
   return {
     root,
     pages: [
-      { source: 'docs/a.md', route: 'en/a.md', label: 'A', sidebar: 'en-docs', section: 'Test', order: 1 },
-      { source: 'docs/b.md', route: 'en/reference/b.md', label: 'B', sidebar: 'en-docs', section: 'Test', order: 2 },
+      { locale: 'root', contentLocale: 'en-US', source: 'docs/a.md', route: 'a.md', label: 'A', sidebar: 'zh-reference', section: 'Test', order: 1 },
+      { locale: 'root', contentLocale: 'en-US', source: 'docs/b.md', route: 'reference-root/b.md', label: 'B', sidebar: 'zh-reference', section: 'Test', order: 2 },
+      { locale: 'en', contentLocale: 'en-US', source: 'docs/a.md', route: 'en/a.md', label: 'A', sidebar: 'en-reference', section: 'Test', order: 1 },
+      { locale: 'en', contentLocale: 'en-US', source: 'docs/b.md', route: 'en/reference/b.md', label: 'B', sidebar: 'en-reference', section: 'Test', order: 2 },
     ],
   }
 }
@@ -36,6 +38,7 @@ describe('rewriteMarkdown', () => {
     const { root, pages } = fixture()
     const source = '[B](b.md#part) [source](../packages/tool.ts:2) [web](https://example.com)\n'
     expect(rewriteMarkdown(source, {
+      locale: 'en',
       sourcePath: 'docs/a.md',
       route: 'en/a.md',
       pages,
@@ -48,9 +51,22 @@ describe('rewriteMarkdown', () => {
     )
   })
 
+  it('selects the published target in the current site locale', () => {
+    const { root, pages } = fixture()
+    expect(rewriteMarkdown('[B](b.md)\n', {
+      locale: 'root',
+      sourcePath: 'docs/a.md',
+      route: 'a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+    })).toBe('[B](./reference-root/b.md)\n')
+  })
+
   it('uses raw GitHub content for unpublished images', () => {
     const { root, pages } = fixture()
     expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
+      locale: 'en',
       sourcePath: 'docs/a.md',
       route: 'en/a.md',
       pages,
@@ -63,6 +79,7 @@ describe('rewriteMarkdown', () => {
     const { root, pages } = fixture()
     const source = '```md\n[B](b.md)\n```\n'
     expect(rewriteMarkdown(source, {
+      locale: 'en',
       sourcePath: 'docs/a.md',
       route: 'en/a.md',
       pages,
@@ -74,6 +91,7 @@ describe('rewriteMarkdown', () => {
   it('fails loud when a relative target is missing', () => {
     const { root, pages } = fixture()
     expect(() => rewriteMarkdown('[missing](missing.md)\n', {
+      locale: 'en',
       sourcePath: 'docs/a.md',
       route: 'en/a.md',
       pages,
@@ -83,6 +101,19 @@ describe('rewriteMarkdown', () => {
   })
 })
 
+describe('docsPages locale routes', () => {
+  it('publishes the same canonical source at every corresponding locale route', () => {
+    const byRoute = new Map(docsPages.map(page => [page.route, page]))
+    for (const page of docsPages.filter(page => page.locale === 'root')) {
+      const counterpart = byRoute.get(`en/${page.route}`)
+      expect(counterpart, page.route).toBeDefined()
+      expect(counterpart?.locale).toBe('en')
+      expect(counterpart?.source).toBe(page.source)
+      expect(counterpart?.contentLocale).toBe(page.contentLocale)
+    }
+  })
+})
+
 describe('addProjectionFrontmatter', () => {
   it('adds frontmatter to an ordinary Markdown page', () => {
     expect(addProjectionFrontmatter('# Guide\n', 'docs/guide.md')).toBe(

scripts/project-doc-site.ts

@@ -11,7 +11,7 @@ import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
 import type { Nodes } from 'mdast'
-import { docsPages, type DocsPage } from '../website/docs.ts'
+import { docsPages, type DocsLocale, type DocsPage } from '../website/docs.ts'
 
 const REPOSITORY_URL = 'https://github.com/deepseek-harness/deepseek-harness'
 const root = resolve(import.meta.dirname, '..')
@@ -25,6 +25,7 @@ interface Replacement {
 
 /** Inputs for rewriting one canonical Markdown page. */
 export interface RewriteMarkdownOptions {
+  locale: DocsLocale
   sourcePath: string
   route: string
   pages: DocsPage[]
@@ -62,14 +63,16 @@ function routeTarget(fromRoute: string, toRoute: string, suffix: string): string
   return `${target.startsWith('.') ? target : `./${target}`}${suffix}`
 }
 
-function sourceMap(pages: DocsPage[]): Map<string, DocsPage> {
-  const map = new Map<string, DocsPage>()
+function sourceMap(pages: DocsPage[]): Map<string, Map<DocsLocale, DocsPage>> {
+  const map = new Map<string, Map<DocsLocale, DocsPage>>()
   for (const page of pages) {
     for (const source of [page.source, ...(page.sourceAliases ?? [])]) {
-      if (map.has(source)) {
-        throw new Error(`project-doc-site: duplicate source or alias ${JSON.stringify(source)}.`)
+      const localized = map.get(source) ?? new Map<DocsLocale, DocsPage>()
+      if (localized.has(page.locale)) {
+        throw new Error(`project-doc-site: duplicate source or alias ${JSON.stringify(source)} for locale ${JSON.stringify(page.locale)}.`)
       }
-      map.set(source, page)
+      localized.set(page.locale, page)
+      map.set(source, localized)
     }
   }
   return map
@@ -132,7 +135,7 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
     if (path === '') return
     const { absPath, line } = resolveRepositoryTarget(sourceAbs, path, options.repoRoot)
     const targetPath = repoPath(absPath, options.repoRoot)
-    const page = published.get(targetPath)
+    const page = published.get(targetPath)?.get(options.locale)
     const nextUrl = page === undefined
       ? githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
       : routeTarget(options.route, page.route, suffix)
@@ -205,6 +208,7 @@ export function projectDocs(): void {
     const markdown = readFileSync(sourceAbs, 'utf8')
     const projected = rewriteMarkdown(markdown, {
       sourcePath: page.source,
+      locale: page.locale,
       route: page.route,
       pages: docsPages,
       repoRoot: root,