Skip to content
Open
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
3 changes: 2 additions & 1 deletion .github/workflows/canary-aliyun.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- name: Install ossutil
run: |
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/canary-cloudflare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- uses: oven-sh/setup-bun@v2

Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/canary.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- name: Install ossutil
run: |
Expand Down
9 changes: 6 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- name: Download ossutils zip
run: |
Expand Down Expand Up @@ -76,7 +77,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- uses: oven-sh/setup-bun@v2

Expand Down Expand Up @@ -113,7 +115,8 @@ jobs:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
# 全量历史:src/lib/last-updated.ts 按提交记录取文档更新日期(sitemap lastmod、页面 Last Updated),浅克隆时取不到
fetch-depth: 0

- name: Download ossutils zip
run: |
Expand Down
10 changes: 9 additions & 1 deletion astro.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import remarkDirective from 'remark-directive'
import { remarkCallout } from './src/integrations/remark-callout'
import { regionHostnameRewrite } from './src/integrations/region-hostname-rewrite'
import { sitemapLocaleFiles } from './src/integrations/sitemap-locale-files'
import { sitemapLastmod } from './src/lib/sitemap-lastmod'
import { prebuildMcpTools } from './src/integrations/prebuild-mcp-tools'
import { prebuildSkills } from './src/integrations/prebuild-skills'

Expand Down Expand Up @@ -118,7 +119,14 @@ export default defineConfig({
const isZh = /^\/zh-(CN|HK)(\/|$)/.test(new URL(item.url).pathname)
const links = item.links ?? (isZh ? [] : [{ url: item.url, lang: 'en' }])
const en = links.find((l) => l.lang === 'en')
return { ...item, links: en ? [...links, { url: en.url, lang: 'x-default' }] : item.links }
// lastmod = 源文件最近一次提交日期(src/lib/sitemap-lastmod.ts);
// 取不到真实日期的页面(首页、API Reference 等)不写,不用构建当天兜底。
const lastmod = sitemapLastmod(item.url)
return {
...item,
...(lastmod ? { lastmod } : {}),
links: en ? [...links, { url: en.url, lang: 'x-default' }] : item.links,
}
},
// 按语言分组,再由 sitemapLocaleFiles 落到 /{en,zh-CN,zh-HK}/sitemap.xml,
// 总索引为 /sitemap.xml。
Expand Down
68 changes: 68 additions & 0 deletions src/lib/last-updated.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
import { describe, expect, it } from 'vitest'
import { lookupLastUpdated, parseGitLog } from './last-updated'

// `git log --no-merges --no-renames --format=%cI --name-only HEAD -- docs`,新提交在前。
const LOG = `2026-11-09T10:00:00+08:00

docs/en/docs/cli/orders/exchange-rate.mdx
docs/zh-CN/docs/cli/orders/exchange-rate.mdx

2026-10-22T09:30:00+08:00

docs/en/docs/socket/protocol/how-to-parse-push.mdx
docs/en/docs/cli/orders/exchange-rate.mdx

2026-08-17T12:00:00+08:00

docs/en/docs/getting-started.mdx
docs/en/docs/cli/index.mdx

2026-03-01T12:00:00+08:00

docs/en/docs/getting-started.md
docs/en/docs/cli.md
docs/en/docs/legacy-only.md
`

describe('parseGitLog', () => {
const map = parseGitLog(LOG)

it('每个文件取第一次出现(最近一次提交)的日期', () => {
expect(map.get('docs/en/docs/cli/orders/exchange-rate.mdx')).toBe('2026-11-09T10:00:00+08:00')
expect(map.get('docs/en/docs/socket/protocol/how-to-parse-push.mdx')).toBe('2026-10-22T09:30:00+08:00')
})

it('只收 docs/ 下的路径', () => {
expect([...map.keys()].every((k) => k.startsWith('docs/'))).toBe(true)
})

it('空输出得到空表', () => {
expect(parseGitLog('').size).toBe(0)
})
})

describe('lookupLastUpdated', () => {
const map = parseGitLog(LOG)

it('认 .mdx 文件', () => {
expect(lookupLastUpdated(map, 'en/docs/cli/orders/exchange-rate')).toBe('2026-11-09T10:00:00+08:00')
expect(lookupLastUpdated(map, 'zh-CN/docs/cli/orders/exchange-rate')).toBe('2026-11-09T10:00:00+08:00')
})

it('.mdx 和迁移前的 .md 都有时取较新的', () => {
expect(lookupLastUpdated(map, 'en/docs/getting-started')).toBe('2026-08-17T12:00:00+08:00')
})

it('foo/index.mdx 兜底找迁移前的 foo.md,仍取较新的', () => {
expect(lookupLastUpdated(map, 'en/docs/cli/index')).toBe('2026-08-17T12:00:00+08:00')
})

it('只有旧 .md 的记录时用它', () => {
expect(lookupLastUpdated(map, 'en/docs/legacy-only')).toBe('2026-03-01T12:00:00+08:00')
})

it('查不到返回 null,不编日期', () => {
expect(lookupLastUpdated(map, 'en/docs/not-in-git')).toBeNull()
expect(lookupLastUpdated(new Map(), 'en/docs/getting-started')).toBeNull()
})
})
101 changes: 61 additions & 40 deletions src/lib/last-updated.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,67 +3,88 @@ import { execSync } from 'node:child_process'
/**
* Per-file "last updated" dates for docs, sourced from git.
*
* This branch's migration commit bulk-rewrote every `.md` → `.mdx`, so the
* .mdx files on HEAD all share that one commit date — useless for a "Last
* Updated" line. The REAL per-page dates live in the pre-migration `.md`
* files' history on `origin/main`. We read those once (a single `git log`
* for the whole docs tree, memoised at module scope so the whole build/dev
* process pays for it exactly once) and map them back to `.mdx` entry ids.
* One `git log` over the whole docs tree (memoised at module scope, so the
* build pays for it once) gives the latest commit date of every file. Used by
* the "Last Updated" line (DocMeta.astro) and the sitemap `<lastmod>`
* (src/lib/sitemap-lastmod.ts).
*
* Everything degrades gracefully: if `origin/main` isn't available (e.g. a
* shallow CI checkout) or git errors, the map is empty and callers simply
* omit the Last Updated line rather than showing a wrong date.
* Files are `.mdx` today; the pre-migration `.md` paths are still looked up as
* a fallback, and when both exist the newer date wins.
*
* Everything degrades gracefully: on a shallow clone (CI `fetch-depth: 1`),
* or when git errors, the map is empty and callers omit the date rather than
* show a wrong one. A shallow clone is treated as "unknown" on purpose: its
* boundary commit looks like a root commit that adds every file, which would
* stamp every page with the build-day commit date.
*/

let cache: Map<string, string> | null = null

/** Build `{ "docs/en/docs/getting-started.md" → ISO date }` from origin/main. */
function buildMap(): Map<string, string> {
/**
* Parse `git log --format=%cI --name-only` output (newest first) into
* `{ "docs/en/docs/getting-started.mdx" → ISO date }`. The first time a path
* appears is its latest commit.
*/
export function parseGitLog(out: string): Map<string, string> {
const map = new Map<string, string>()
let out = ''
try {
// Newest-first commit log with the files each touched. `%cI` on its own
// line marks a commit; `docs/…` lines are the files. The FIRST time a
// file appears (walking newest→oldest) is its latest commit.
out = execSync('git log --no-merges --format=%cI --name-only origin/main -- docs', {
encoding: 'utf8',
cwd: process.cwd(),
maxBuffer: 64 * 1024 * 1024,
stdio: ['ignore', 'pipe', 'ignore'],
})
} catch {
return map // origin/main missing or git unavailable → empty (feature hides)
}
let currentDate = ''
for (const line of out.split('\n')) {
for (const raw of out.split('\n')) {
const line = raw.trim()
if (/^\d{4}-\d\d-\d\dT/.test(line)) {
currentDate = line.trim()
currentDate = line
} else if (line.startsWith('docs/') && currentDate && !map.has(line)) {
map.set(line, currentDate)
}
}
return map
}

function git(args: string): string {
return execSync(`git ${args}`, {
encoding: 'utf8',
cwd: process.cwd(),
maxBuffer: 64 * 1024 * 1024,
stdio: ['ignore', 'pipe', 'ignore'],
})
}

function buildMap(): Map<string, string> {
try {
if (git('rev-parse --is-shallow-repository').trim() !== 'false') return new Map()
// HEAD = the commit being built (main on release, the branch on canary).
// --no-renames: list paths as-is, and avoid rename detection fetching
// blobs on partial (blob:none) clones.
return parseGitLog(git('log --no-merges --no-renames --format=%cI --name-only HEAD -- docs'))
} catch {
return new Map() // not a git checkout / git unavailable → feature hides
}
}

function getMap(): Map<string, string> {
if (!cache) cache = buildMap()
return cache
}

/** Newer of two ISO dates (either may be missing). */
function newer(a: string | undefined, b: string | undefined): string | undefined {
if (!a) return b
if (!b) return a
return Date.parse(b) > Date.parse(a) ? b : a
}

/**
* Latest commit date (ISO string) for a docs entry, or null if unknown.
* `id` is the collection entry id (file path without extension), e.g.
* `en/docs/getting-started` or `en/docs/cli/index`.
* Look up `id` (collection entry id = file path without extension, e.g.
* `en/docs/getting-started` or `en/docs/cli/index`) in a path → date map.
*/
export function lookupLastUpdated(map: ReadonlyMap<string, string>, id: string): string | null {
let best = map.get(`docs/${id}.mdx`)
best = newer(best, map.get(`docs/${id}.md`))
// Pages migrated from `foo.md` → `foo/index.mdx`.
if (id.endsWith('/index')) best = newer(best, map.get(`docs/${id.replace(/\/index$/, '')}.md`))
return best ?? null
}

/** Latest commit date (ISO string) for a docs entry, or null if unknown. */
export function getLastUpdated(id: string): string | null {
const map = getMap()
// Direct `.md` twin of the current `.mdx` path…
const direct = `docs/${id}.md`
if (map.has(direct)) return map.get(direct)!
// …and the flattened form for pages migrated from `foo.md` → `foo/index.mdx`.
if (id.endsWith('/index')) {
const flat = `docs/${id.replace(/\/index$/, '')}.md`
if (map.has(flat)) return map.get(flat)!
}
return null
return lookupLastUpdated(getMap(), id)
}
84 changes: 84 additions & 0 deletions src/lib/sitemap-lastmod.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import { buildUrlToId, createLastmodResolver, readDocSources, urlPath, type DocSource } from './sitemap-lastmod'

const HOST = 'https://open.longbridge.com'

const SOURCES: DocSource[] = [
{ id: 'en/index', data: { layout: false } },
{ id: 'en/sdk', data: {} },
{ id: 'en/docs/index', data: {} },
{ id: 'en/docs/api', data: { layout: 'api-reference' } },
{ id: 'en/docs/cli/orders/exchange-rate', data: {} },
{ id: 'en/docs/socket/protocol/how-to-parse-push', data: { slug: '/socket/protocol/push' } },
{ id: 'zh-CN/docs/socket/protocol/how-to-parse-push', data: { slug: '/socket/protocol/push' } },
{ id: 'zh-HK/docs/cli/index', data: {} },
]

const DATES: Record<string, string> = {
'en/index': '2026-11-20T00:00:00+08:00',
'en/sdk': '2026-11-20T00:00:00+08:00',
'en/docs/index': '2026-09-01T00:00:00+08:00',
'en/docs/api': '2026-11-20T00:00:00+08:00',
'en/docs/cli/orders/exchange-rate': '2026-11-09T10:00:00+08:00',
'en/docs/socket/protocol/how-to-parse-push': '2026-10-22T09:30:00+08:00',
'zh-CN/docs/socket/protocol/how-to-parse-push': '2026-10-23T09:30:00+08:00',
}

const lastmod = createLastmodResolver(buildUrlToId(SOURCES), (id) => DATES[id] ?? null)

describe('urlPath', () => {
it('去掉域名、尾斜杠和 .html', () => {
expect(urlPath(`${HOST}/docs/cli/`)).toBe('/docs/cli')
expect(urlPath(`${HOST}/docs/cli.html`)).toBe('/docs/cli')
expect(urlPath(`${HOST}/`)).toBe('/')
})
})

describe('sitemap lastmod', () => {
it('普通 .mdx 文档页按文件路径对上日期', () => {
expect(lastmod(`${HOST}/docs/cli/orders/exchange-rate`)).toBe('2026-11-09T10:00:00+08:00')
})

it('frontmatter slug 指定的网址对到真正的源文件', () => {
expect(lastmod(`${HOST}/docs/socket/protocol/push`)).toBe('2026-10-22T09:30:00+08:00')
expect(lastmod(`${HOST}/zh-CN/docs/socket/protocol/push`)).toBe('2026-10-23T09:30:00+08:00')
// 按网址拼出来的文件名不存在,不能误配
expect(lastmod(`${HOST}/docs/socket/protocol/how-to-parse-push`)).toBeUndefined()
})

it('index.mdx 对应目录网址', () => {
expect(lastmod(`${HOST}/docs`)).toBe('2026-09-01T00:00:00+08:00')
})

it('取不到日期的不写', () => {
// 源文件没有提交记录
expect(lastmod(`${HOST}/zh-HK/docs/cli`)).toBeUndefined()
// API Reference:/docs/api 是 api-reference 布局,/docs/api/<op> 由 openapi.yaml 生成
expect(lastmod(`${HOST}/docs/api`)).toBeUndefined()
expect(lastmod(`${HOST}/docs/api/get-quote`)).toBeUndefined()
// 首页、营销页内容不在 .mdx 里
expect(lastmod(`${HOST}/`)).toBeUndefined()
expect(lastmod(`${HOST}/sdk`)).toBeUndefined()
})

it('git 历史为空(浅克隆)时一条都不写', () => {
const none = createLastmodResolver(buildUrlToId(SOURCES), () => null)
expect(none(`${HOST}/docs/cli/orders/exchange-rate`)).toBeUndefined()
})
})

describe('readDocSources(仓库真实文档)', () => {
const urlToId = buildUrlToId(readDocSources(join(process.cwd(), 'docs')))

it('slug 改过网址的页面三种语言都能对上源文件', () => {
expect(urlToId.get('/docs/socket/protocol/push')).toBe('en/docs/socket/protocol/how-to-parse-push')
expect(urlToId.get('/zh-CN/docs/socket/protocol/push')).toBe('zh-CN/docs/socket/protocol/how-to-parse-push')
expect(urlToId.get('/zh-HK/docs/socket/protocol/push')).toBe('zh-HK/docs/socket/protocol/how-to-parse-push')
})

it('不含 API Reference 和首页', () => {
expect(urlToId.has('/docs/api')).toBe(false)
expect(urlToId.has('/')).toBe(false)
})
})
Loading
Loading