Files
ClassHelper/docs/build.mjs
T

129 lines
5.2 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env node
/**
* 文档站构建脚本 —— `pnpm docs:build`。
*
* 为什么不用直接跑 `docfx docs/docfx.json`:
* 1) 站点版本号取自根 package.json(单一来源),DocFX 的配置文件是静态 JSON、读不了文件,
* 只能用 CLI 的 `--metadata` 传进去(模板里以 `{{_chVersion}}` 引用);
* 2) GitHub Pages 的项目页挂在 /<仓库名>/ 子路径下,404 页里的相对链接必须相对**站点根**
* 而不是相对被请求的那个不存在的路径,因此 404 页的 `<base>` 由这里注入(DOCS_BASE 控制)。
*
* 用法:
* node docs/build.mjs # 构建到 docs/_site
* DOCS_BASE=/classhelper/ node docs/build.mjs
* node docs/build.mjs --check # 构建并把 docfx 的警告当成错误(CI / 交付前用)
* node docs/build.mjs --serve # 构建完起本地预览(等价于再跑 docs/serve.mjs)
*/
import { spawn, spawnSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const here = path.dirname(fileURLToPath(import.meta.url));
const root = path.resolve(here, '..');
const siteDir = path.join(here, '_site');
/** 站点根路径。CI 里按仓库名传进来;本地预览用 './'。 */
const BASE = process.env.DOCS_BASE ?? './';
function readVersion() {
const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
return pkg.version;
}
/** 找不到 docfx 时给出可照抄的安装命令,而不是一句 spawn ENOENT */
function ensureDocfx() {
const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8' });
if (probe.status === 0) return probe.stdout.trim();
console.error('[docs] 找不到 docfx。docfx 是 .NET 工具,安装方式:');
console.error('');
console.error(' dotnet tool install --global docfx');
console.error('');
console.error(' 需要 .NET SDK 8(判据是 `dotnet --list-sdks` 有输出)。');
console.error(' 想把工具装进仓库内(不污染全局):');
console.error(' DOTNET_CLI_HOME=./.cache/dotnet-home NUGET_PACKAGES=./.cache/nuget \\');
console.error(' dotnet tool install --global docfx');
process.exit(2);
}
function run(command, args, options = {}) {
return new Promise((resolve, reject) => {
const child = spawn(command, args, { stdio: 'inherit', ...options });
child.on('error', reject);
child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`))));
});
}
/**
* 清空上一轮的产物。docfx 不负责清理,旧文件(改过名 / 删掉的页面)会一直留着,
* 而 GitHub Pages 上传的是整个目录 —— 不清就会把已下线的页面继续挂在线上。
*/
function cleanSite() {
const sleep = (ms) => {
const until = Date.now() + ms;
while (Date.now() < until) {
/* 同步等待:这是构建脚本,不值得为几毫秒引入异步 */
}
};
for (let attempt = 1; attempt <= 5; attempt += 1) {
try {
fs.rmSync(siteDir, { recursive: true, force: true });
return;
} catch (error) {
if (attempt === 5) {
throw new Error(
`清不掉 ${path.relative(root, siteDir)}(${error.code ?? error.message})。` +
' 多半是预览服务或编辑器正占用它 —— 关掉再试。',
);
}
sleep(250 * attempt);
}
}
}
/**
* 生成 404 页。
* GitHub Pages 对项目页的未知路径返回站点根的 404.html,而浏览器是**按请求的路径**解析相对链接的,
* 所以页面里的 <base> 必须显式指向站点根,否则 /classhelper/get-started/typo 会去解析
* /classhelper/get-started/ 下的链接。本地预览时 BASE 为 './',正好等价于同目录。
*/
function writeNotFound() {
const template = fs.readFileSync(path.join(here, '404.html'), 'utf8');
const html = template.replaceAll('{{BASE}}', BASE);
fs.writeFileSync(path.join(siteDir, '404.html'), html, 'utf8');
console.log(`[docs] 404.html(base = ${BASE})`);
}
async function main() {
const version = readVersion();
const docfxVersion = ensureDocfx();
console.log(`[docs] docfx ${docfxVersion} · 站点版本 ${version}`);
// --check:把警告当错误。最常见的警告是"某个 .md 没被任何 toc.yml 引用",
// 那种页面会被构建出来但没有侧边栏,属于必须修掉的疏漏。
const check = process.argv.includes('--check');
const args = ['build', 'docfx.json', '--metadata', `_chVersion=${version}`];
if (check) args.push('--warningsAsErrors');
// docfx 只覆盖、不清理:删掉或改名的页面会以旧文件的形式留在 _site 里,
// 而 GitHub Pages 上传的是整个目录 —— 不清理就会把已经下线的页面继续挂在线上。
// Windows 上目录偶尔会被瞬时占用(编辑器 / 索引 / 预览进程),所以重试几次再放弃。
cleanSite();
await run('docfx', args, { cwd: here });
writeNotFound();
console.log(`[docs] 完成:${path.relative(root, siteDir)}`);
if (process.argv.includes('--serve')) {
await run(process.execPath, [path.join(here, 'serve.mjs')]);
}
}
main().catch((error) => {
console.error('[docs] 失败:', error.message);
process.exit(1);
});