feat: publish markdown sources and a blob index under /docs-api

.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)

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/<path>`, 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.

public/_headers

@@ -0,0 +1,2 @@
+/docs-api/raw/*
+  Content-Type: text/plain; charset=utf-8

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) })
+    }
+  })
+})

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<void> {
+  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 }))
+}