From e7c7c838e9a9655cddde9f33255e7e2801bda917 Mon Sep 17 00:00:00 2001 From: m1ngsama Date: Sat, 26 Sep 2026 22:28:15 +0800 Subject: [PATCH] feat: publish markdown sources and a blob index under /docs-api --- .vitepress/config.mts | 2 ++ CONTRIBUTING.md | 2 ++ public/_headers | 2 ++ utils/docs-api.test.ts | 35 +++++++++++++++++++++++++++++++++++ utils/docs-api.ts | 20 ++++++++++++++++++++ 5 files changed, 61 insertions(+) create mode 100644 public/_headers create mode 100644 utils/docs-api.test.ts create mode 100644 utils/docs-api.ts diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 10e35728..f7beced4 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,5 +1,6 @@ import { fileURLToPath, URL } from 'node:url' import { withMermaid } from 'vitepress-plugin-mermaid' +import { publishSources } from '../utils/docs-api' import { recentCommitsFor } from '../utils/git-history' import { applyEditorialRules } from '../utils/markdown-pipeline' import { devEditor } from './dev-editor.mjs' @@ -188,6 +189,7 @@ export default withMermaid({ ], lastUpdated: true, sitemap: { hostname: siteUrl }, + buildEnd: ({ srcDir, outDir, pages }) => publishSources(srcDir, outDir, pages), transformPageData(pageData) { const commits = recentCommitsFor(pageData.filePath) if (commits.length) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39aea338..ec3c04e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,8 @@ Deployment settings on the Pages project: - `GITHUB_CLIENT_SECRET` — GitHub OAuth App secret. The client id is public and lives in the source. An upload is accepted only when that secret can vouch for the editor's token. - R2 binding `MEDIA` — bucket for those uploads. `GET /media/…` reads the object back. The name is not `ASSETS`: Pages already uses that for the site files, and a second binding with the same name fails the deploy. Without `MEDIA`, uploads answer 503 and the rest of the site keeps working. Existing pictures stay in the repository. +The build also publishes every page's markdown source under `/docs-api/raw/`, listed with its git blob sha in `/docs-api/index.json`. The [Prompt](https://github.com/nbtca/Prompt) terminal client reads them there because GitHub is unreachable from much of mainland China. The index has the shape of GitHub's recursive tree response, so keep both URLs and that shape stable. + ## Where content goes - `about/`, `tutorial/`, `process/` and `archived/` build their sidebars by scanning the directory. Add a markdown file and it appears; nothing else to edit. diff --git a/public/_headers b/public/_headers new file mode 100644 index 00000000..08286f5b --- /dev/null +++ b/public/_headers @@ -0,0 +1,2 @@ +/docs-api/raw/* + Content-Type: text/plain; charset=utf-8 diff --git a/utils/docs-api.test.ts b/utils/docs-api.test.ts new file mode 100644 index 00000000..283ae4c0 --- /dev/null +++ b/utils/docs-api.test.ts @@ -0,0 +1,35 @@ +import { execFileSync } from 'node:child_process' +import { mkdtemp, readFile, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import path from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { blobSha, publishSources } from './docs-api' + +const outDirs: string[] = [] + +afterEach(async () => { + await Promise.all(outDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) +}) + +describe('docs api', () => { + it('hashes a file the way git hash-object does', async () => { + const file = 'about/index.md' + const expected = execFileSync('git', ['hash-object', file], { encoding: 'utf8' }).trim() + expect(blobSha(await readFile(file))).toBe(expected) + }) + + it('publishes each source byte for byte next to a sorted index', async () => { + const outDir = await mkdtemp(path.join(tmpdir(), 'docs-api-')) + outDirs.push(outDir) + await publishSources('.', outDir, ['index.md', 'about/index.md']) + + const index = JSON.parse(await readFile(path.join(outDir, 'docs-api/index.json'), 'utf8')) + expect(index.truncated).toBe(false) + expect(index.tree.map((item: { path: string }) => item.path)).toEqual(['about/index.md', 'index.md']) + for (const item of index.tree) { + const raw = await readFile(path.join(outDir, 'docs-api/raw', item.path)) + expect(raw.equals(await readFile(item.path))).toBe(true) + expect(item).toEqual({ path: item.path, type: 'blob', sha: blobSha(raw) }) + } + }) +}) diff --git a/utils/docs-api.ts b/utils/docs-api.ts new file mode 100644 index 00000000..cff4e082 --- /dev/null +++ b/utils/docs-api.ts @@ -0,0 +1,20 @@ +import { createHash } from 'node:crypto' +import { mkdir, readFile, writeFile } from 'node:fs/promises' +import path from 'node:path' + +export function blobSha(bytes: Uint8Array): string { + return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex') +} + +// Same shape as GitHub's recursive tree response, so @nbtca/docs reads both with one parser. +export async function publishSources(srcDir: string, outDir: string, pages: string[]): Promise { + const root = path.join(outDir, 'docs-api') + const tree = await Promise.all([...pages].sort().map(async (page) => { + const bytes = await readFile(path.join(srcDir, page)) + const target = path.join(root, 'raw', page) + await mkdir(path.dirname(target), { recursive: true }) + await writeFile(target, bytes) + return { path: page, type: 'blob', sha: blobSha(bytes) } + })) + await writeFile(path.join(root, 'index.json'), JSON.stringify({ tree, truncated: false })) +}