feat(docs): version-bound release documentation served at /docs
Build & Push Docker Image / build (push) Successful in 2m35s

Adds a docs pipeline so each release has a version-bound Markdown
document (docs/releases/vX.Y.Z.md) rendered publicly in the app:

- sync-release-docs.mjs copies docs/releases/*.md into the toolrate
  public dir and generates index.json before every dev/build
- /docs lists all releases; /docs/:version renders the sanitized
  Markdown (marked + DOMPurify, typography styles)
- template + workflow documented in docs/README.md
- current release (v0.6.0) documented as the first entry
This commit is contained in:
opencode
2026-08-03 16:41:08 +02:00
parent d1dd77bc1e
commit 520f917723
14 changed files with 458 additions and 3 deletions
+87
View File
@@ -0,0 +1,87 @@
// Copies docs/releases/*.md into the toolrate frontend's static public dir
// and generates index.json (version list) so the app can render /docs.
//
// Run before `vite build` (Vite copies public/ -> dist/public verbatim), and
// before `vite dev` so the docs are available locally too.
//
// Usage: node scripts/src/sync-release-docs.mjs
import { readdir, readFile, copyFile, mkdir, rm, writeFile } from "node:fs/promises";
import { resolve, join } from "node:path";
import { fileURLToPath } from "node:url";
const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
const sourceDir = resolve(root, "docs/releases");
const targetDir = resolve(root, "artifacts/toolrate/public/docs");
const isReleaseFile = (name) => /^v\d+\.\d+\.\d+\.md$/.test(name);
function parseVersion(name) {
return name.replace(/\.md$/, "");
}
// Semantic-ish comparison: v0.6.0 > v0.5.0 > v0.4.2
function cmp(a, b) {
const pa = parseVersion(a).slice(1).split(".").map(Number);
const pb = parseVersion(b).slice(1).split(".").map(Number);
for (let i = 0; i < 3; i++) {
if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
}
return 0;
}
function extractTitle(content) {
const m = content.match(/^#\s+(.+)$/m);
return m ? m[1].trim() : null;
}
function extractDate(content) {
// e.g. "**Datum:** 2026-08-03" or "**Date:** 2026-08-03" in the header block.
// Match the first ISO date that follows a Datum/Date label, tolerating
// bold markers/colons around it.
const m = content.match(/(?:Datum|Date)[^\d\n]{0,20}(\d{4}-\d{2}-\d{2})/);
return m ? m[1] : null;
}
async function main() {
let names;
try {
names = (await readdir(sourceDir)).filter(isReleaseFile);
} catch (err) {
if (err.code === "ENOENT") {
console.warn(`[sync-release-docs] ${sourceDir} not found; nothing to sync`);
return;
}
throw err;
}
if (names.length === 0) {
console.warn("[sync-release-docs] no release docs found; clearing target dir");
}
names.sort(cmp).reverse();
await rm(targetDir, { recursive: true, force: true });
await mkdir(targetDir, { recursive: true });
const index = [];
for (const name of names) {
const content = await readFile(join(sourceDir, name), "utf8");
await copyFile(join(sourceDir, name), join(targetDir, name));
index.push({
version: parseVersion(name),
file: name,
title: extractTitle(content) ?? parseVersion(name),
date: extractDate(content) ?? null,
});
}
await writeFile(join(targetDir, "index.json"), JSON.stringify(index, null, 2));
console.log(`[sync-release-docs] synced ${names.length} release doc(s) -> ${targetDir}`);
}
main().catch((err) => {
console.error("[sync-release-docs] failed:", err);
process.exit(1);
});