From 4a9ca2988732944ea794e23852132e02c2aec567 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 25 Oct 2026 15:07:49 +0100 Subject: [PATCH] Website: the API portal at /docs/api, with Markdown tables The repository's docs/api/ (the portal, its surface pages and the generated mod and server references) is built into the docs section: /docs/api is its README and /docs/api/ each page, in two nav groups, "Build on Horizon" and "API reference". The pages are read from the checkout or from main on GitHub, like the README, so the site never holds a copy. Links between portal pages become the site's (and the build's link check covers them); other relative links go to the file on GitHub. The renderer gains tables: the "Ways in" table, the references and the other tables on the site (apis, performance) showed as raw pipes. A link whose label is a code span no longer throws. Caddy and the dev server route /docs/api/ and redirect /docs/api/ to /docs/api; Railway rebuilds when docs/api/ changes. /docs/mods links the Mod API, its reference and its ways in; the summary page is now "APIs at a glance". Co-Authored-By: Claude Opus 5.5 --- docs/api/README.md | 3 ++- website/Caddyfile | 4 ++++ website/README.md | 9 ++++++-- website/build.mjs | 34 +++++++++++++++++++++++------- website/docs/apis.md | 4 ++-- website/docs/mods.md | 2 +- website/docs/nav.json | 3 ++- website/railway.json | 2 +- website/serve.mjs | 6 +++++- website/src/docs.html | 2 +- website/src/markdown.js | 39 ++++++++++++++++++++++++++++++++--- website/src/markdown.test.mjs | 25 ++++++++++++++++++++++ website/src/style.css | 4 ++++ 13 files changed, 117 insertions(+), 20 deletions(-) create mode 100644 website/src/markdown.test.mjs diff --git a/docs/api/README.md b/docs/api/README.md index ad49ff609..ef3649105 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -51,5 +51,6 @@ Every page has the same parts: **Overview** (what you can build), **Guide** (whe **Examples**, **Stability** (the level of each part, per [stability.md](stability.md)), **Changelog** and **Not there yet** (what is planned, so nobody builds on a guess). -The website's summary for players and authors is [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis) +The website shows these pages at [playhorizon.dev/docs/api](https://playhorizon.dev/docs/api), built from this +folder, and a summary for players and authors at [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis) (`website/docs/apis.md`). diff --git a/website/Caddyfile b/website/Caddyfile index fb96e836d..4ef85d2fc 100644 --- a/website/Caddyfile +++ b/website/Caddyfile @@ -35,6 +35,10 @@ rewrite /benchmarks /benchmarks.html @doc path_regexp doc ^/docs/([a-z-]+)$ rewrite @doc /docs/{re.doc.1}.html + # The API portal: /docs/api is its index, /docs/api/ its pages. + redir /docs/api/ /docs/api permanent + @apidoc path_regexp apidoc ^/docs/api/([a-z-]+)$ + rewrite @apidoc /docs/api/{re.apidoc.1}.html # The registry's submission service (crates/horizon-mod-registry), over Railway's private network. Unset, the # form says it isn't open. handle /api/mods/* { diff --git a/website/README.md b/website/README.md index 8ced5a0aa..7339cf966 100644 --- a/website/README.md +++ b/website/README.md @@ -77,8 +77,13 @@ mark merged-but-unreleased things "next release". `{{HARNESSES}}` and `{{PERCENT the README. A line holding only `![caption](/media/...)` becomes a figure (the file must be in `public/media/`); links to other pages are `/docs/#heading`. The build checks every link between pages and every image, and fails with the list when one is broken. `/server` -redirects to `/docs/hosting`. The developer docs in the repository's `docs/` stay as they are and are linked from -the Contributing page. +redirects to `/docs/hosting`. + +The API portal is the repository's `docs/api/`, not a copy: `nav.json` lists its README as `api` (`/docs/api`) and +its pages as `api/` (`/docs/api/`), read from the checkout or from `main` on GitHub like the README. +Links between its pages become the site's, every other relative link goes to the file on GitHub, and the same link +check applies. Markdown tables render as tables. The other developer docs in `docs/` stay on GitHub and are linked +from the Contributing page. ## Run it locally diff --git a/website/build.mjs b/website/build.mjs index 12bba71cb..4045297fb 100644 --- a/website/build.mjs +++ b/website/build.mjs @@ -3,12 +3,13 @@ // docs/nav.json), plus public/ and fingerprinted CSS and JS. No dependencies. // // Railway builds only website/, so the README and links.json come from the repo when they -// are next to it (a local checkout) and from main on GitHub otherwise. The documentation lives in website/. The latest releases and +// are next to it (a local checkout) and from main on GitHub otherwise. The documentation lives in website/, except the +// API portal (docs/api/), read the same way as the README. The latest releases and // the contributors are baked in when GitHub answers, so the page reads well before (or without) JavaScript. import { readFile, writeFile, mkdir, rm, cp } from "node:fs/promises"; import { existsSync } from "node:fs"; import { createHash } from "node:crypto"; -import { join, dirname } from "node:path"; +import { join, dirname, posix } from "node:path"; import { fileURLToPath } from "node:url"; import { markdown, inline, section, escape } from "./src/markdown.js"; import { recentHtml, releasesPageHtml } from "./src/releases.js"; @@ -303,16 +304,35 @@ const values = { // --- The documentation --------------------------------------------------------------------- // website/docs/.md: "# Title", a one-paragraph lede, then the body. docs/nav.json orders them in groups. +// The API portal is the repository's docs/api/ (the pages and their generated references): nav.json lists it as +// `api` (its README, /docs/api) and `api/` (/docs/api/). Its links are written for GitHub, so links +// between its pages become the site's and every other relative link goes to the file on GitHub. const docsNav = JSON.parse(await readFile(join(site, "docs", "nav.json"), "utf8")); +const docSlugs = new Set(docsNav.flatMap((g) => g.pages)); +const apiSource = (slug) => `docs/api/${slug === "api" ? "README" : slug.slice(4)}.md`; +function apiLinks(text, from) { + return text.replace(/\]\(([^)\s]+)\)/g, (all, url) => { + if (url.startsWith("https://playhorizon.dev/")) return `](${url.slice(23)})`; + if (/^([a-z]+:|#|\/)/i.test(url)) return all; + const [file, id] = url.split("#"); + const path = posix.normalize(posix.join(posix.dirname(from), file)); + const page = path.match(/^docs\/api\/([\w-]+)\.md$/)?.[1]; + const slug = page === "README" ? "api" : page && `api/${page}`; + const to = docSlugs.has(slug) ? `/docs/${slug}` : `https://github.com/${REPO}/blob/main/${path}`; + return `](${to}${id ? `#${id}` : ""})`; + }); +} const docs = []; for (const { group, pages: slugs } of docsNav) { for (const slug of slugs) { - const file = `${slug}.md`; - const text = (await readFile(join(site, "docs", file), "utf8")).replace(/\r\n?/g, "\n"); + const api = slug === "api" || slug.startsWith("api/"); + const file = api ? apiSource(slug) : `website/docs/${slug}.md`; + let text = (api ? (await repoFile(file))[0] : await readFile(join(site, "docs", `${slug}.md`), "utf8")).replace(/\r\n?/g, "\n"); + if (api) text = apiLinks(text.replace(/^\n/, ""), file); const m = text.match(/^# (.+)\n\n((?:[^\n]+\n)+)\n/); - if (!m) throw new Error(`docs/${file}: needs "# Title", a blank line, a lede paragraph and a blank line`); - docs.push({ slug, file, group, title: m[1].trim(), lede: m[2].trim().replace(/\n/g, " "), body: text.slice(m[0].length), path: slug === "index" ? "/docs/" : `/docs/${slug}` }); + if (!m) throw new Error(`${file}: needs "# Title", a blank line, a lede paragraph and a blank line`); + docs.push({ slug, file, group, title: m[1].replace(/`/g, "").trim(), lede: m[2].trim().replace(/\n/g, " "), body: text.slice(m[0].length), path: slug === "index" ? "/docs/" : `/docs/${slug}` }); } } const plain = (md) => md.replace(/`/g, "").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/\*\*/g, ""); @@ -352,7 +372,7 @@ const docNav = (current) => .join("\n"); const pagerLink = (d, rel) => (d ? `${rel === "next" ? "Next" : "Previous"}${escape(d.title)}` : ""); -await mkdir(join(dist, "docs"), { recursive: true }); +await mkdir(join(dist, "docs", "api"), { recursive: true }); const docPageFiles = []; const docPages = renderedDocs.map((d, i) => { const toc = d.headings.filter((h) => h.level === 2); diff --git a/website/docs/apis.md b/website/docs/apis.md index f948b1d54..fbed5fe53 100644 --- a/website/docs/apis.md +++ b/website/docs/apis.md @@ -1,4 +1,4 @@ -# Horizon's APIs +# APIs at a glance Horizon is built to be built on. Mods, shaders, agents, server panels, launchers' scripts and tools all get a documented API with a version, a stability level and a reference generated from the code, so it never says something the game doesn't do. @@ -13,7 +13,7 @@ Horizon is built to be built on. Mods, shaders, agents, server panels, launchers | **Launcher** | your agent, pack makers | `horizon-launcher`'s 46 commands and its MCP server | preview | | **Data formats** | tools that read Horizon's files | benchmark reports, telemetry, settings, release checksums; worlds are vanilla's format | per format | -The full pages, one per surface, are in the repository: [docs/api](https://github.com/ludovic111/horizon/tree/main/docs/api). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting). +The full pages, one per surface, with their references: [the API portal](/docs/api), starting with [the Mod API](/docs/api/mods). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting). ## What the levels mean diff --git a/website/docs/mods.md b/website/docs/mods.md index 0c125cf73..77a1734fd 100644 --- a/website/docs/mods.md +++ b/website/docs/mods.md @@ -30,7 +30,7 @@ cd my-mod cargo horizon-mod run ``` -`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The full guide, with the API, the manifest and the roadmap, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)). +`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The [Mod API](/docs/api/mods) lists what a mod can do today, its [reference](/docs/api/mods-reference), the [ways in](/docs/api/mods#ways-in) (Rust today, Lua scripts planned) and what comes next; the full guide, with the manifest and the runtime, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)). ## Finding resource packs and modpacks diff --git a/website/docs/nav.json b/website/docs/nav.json index 3bc2ec8d2..18eab69fd 100644 --- a/website/docs/nav.json +++ b/website/docs/nav.json @@ -3,6 +3,7 @@ { "group": "Playing", "pages": ["settings", "multiplayer", "troubleshooting"] }, { "group": "Hosting", "pages": ["hosting"] }, { "group": "Going further", "pages": ["modpacks", "mods", "performance", "agents"] }, - { "group": "Build on Horizon", "pages": ["apis"] }, + { "group": "Build on Horizon", "pages": ["apis", "api", "api/stability"] }, + { "group": "API reference", "pages": ["api/mods", "api/mods-reference", "api/mod-index", "api/server", "api/server-reference", "api/agent-control", "api/launcher", "api/data-formats", "api/shaders"] }, { "group": "Project", "pages": ["contributing", "faq"] } ] diff --git a/website/railway.json b/website/railway.json index 0f84cf952..3bbe9dfb3 100644 --- a/website/railway.json +++ b/website/railway.json @@ -3,7 +3,7 @@ "build": { "builder": "DOCKERFILE", "dockerfilePath": "Dockerfile", - "watchPatterns": ["/website/**", "/README.md", "/launcher/links.json"] + "watchPatterns": ["/website/**", "/README.md", "/launcher/links.json", "/docs/api/**"] }, "deploy": { "healthcheckPath": "/", diff --git a/website/serve.mjs b/website/serve.mjs index 761eef48a..6159474a0 100644 --- a/website/serve.mjs +++ b/website/serve.mjs @@ -11,6 +11,10 @@ const port = Number(process.env.PORT) || 4173; createServer(async (req, res) => { let path = normalize(decodeURIComponent(new URL(req.url, "http://x").pathname)).replace(/^(\.\.[/\\])+/, ""); + if (path === "/docs/api/") { + res.writeHead(301, { Location: "/docs/api" }); + return res.end(); + } if (path.endsWith("/")) path += "index.html"; // The server guide is part of the docs now, as the Caddyfile redirects it. if (path === "/server" || path === "/server.html") { @@ -18,7 +22,7 @@ createServer(async (req, res) => { return res.end(); } if (path === "/docs") path = "/docs/index.html"; - // /privacy and /docs/ are .html files, as the Caddyfile rewrites them. + // /privacy, /docs/ and /docs/api/ are .html files, as the Caddyfile rewrites them. if (!extname(path)) path += ".html"; let file = join(root, path); let status = 200; diff --git a/website/src/docs.html b/website/src/docs.html index 1277803b5..56ba89c09 100644 --- a/website/src/docs.html +++ b/website/src/docs.html @@ -46,7 +46,7 @@ -

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.

+

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.

diff --git a/website/src/markdown.js b/website/src/markdown.js index 252e554ec..1735f7304 100644 --- a/website/src/markdown.js +++ b/website/src/markdown.js @@ -1,5 +1,5 @@ -// A small Markdown renderer for release notes and the README: headings, paragraphs, -// lists (nested by indentation), fenced code, quotes, rules, and inline code, bold, +// A small Markdown renderer for release notes, the README and the docs: headings, paragraphs, +// lists (nested by indentation), fenced code, quotes, rules, tables, and inline code, bold, // italic and links. Everything is escaped first, so its output never carries raw HTML. // Shared by build.mjs (Node) and main.js (browser). @@ -38,12 +38,41 @@ export function inline(text, site = false) { out = out.replace(/\u0001(\d+)\u0001/g, (_, i) => { const [label, url] = links[i]; const target = href(url, site); - const body = inline(label, site); + // The label's code spans are already placeholders: put them back for its own pass. + const body = inline(label.replace(/\u0000(\d+)\u0000/g, (_, c) => `\`${codes[c]}\``), site); return target ? `${body}` : body; }); return out.replace(/\u0000(\d+)\u0000/g, (_, i) => `${escape(codes[i])}`); } +// A table: a row of cells, a rule row (`| --- | :-: |`), then body rows, until a line that isn't a row. +const ROW = /^\s*\|.*\|\s*$/; +const RULE = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/; + +/** A row's cells: split on `|` outside code spans; `\|` is a literal bar. */ +function cells(row) { + const s = row.trim().slice(1, -1); + const out = [""]; + let code = false; + for (let i = 0; i < s.length; i++) { + if (s[i] === "\\" && s[i + 1] === "|") out[out.length - 1] += s[++i]; + else if (s[i] === "|" && !code) out.push(""); + else { + if (s[i] === "`") code = !code; + out[out.length - 1] += s[i]; + } + } + return out.map((c) => c.trim()); +} + +function table(lines, start, site) { + const row = (line, tag) => `${cells(line).map((c) => `<${tag}>${inline(c, site)}`).join("")}`; + let i = start + 2; + const body = []; + while (i < lines.length && ROW.test(lines[i])) body.push(row(lines[i++], "td")); + return [`
${row(lines[start], "th")}${body.join("")}
`, i]; +} + const indentOf = (line) => line.match(/^ */)[0].length; const ITEM = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/; @@ -131,6 +160,10 @@ export function markdown(source, { shift = 0, site = false, headings = null } = } else if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) { out.push("
"); i++; + } else if (ROW.test(line) && RULE.test(lines[i + 1] || "")) { + const [html, end] = table(lines, i, site); + out.push(html); + i = end; } else if (ITEM.test(line)) { const [html, end] = list(lines, i, site); out.push(html); diff --git a/website/src/markdown.test.mjs b/website/src/markdown.test.mjs new file mode 100644 index 000000000..171348e45 --- /dev/null +++ b/website/src/markdown.test.mjs @@ -0,0 +1,25 @@ +// node --test src/: the Markdown the docs pages and release notes are rendered from. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { markdown } from "./markdown.js"; + +test("a table renders with its header, cells and inline Markdown", () => { + const html = markdown("| Way in | Status |\n| --- | :-: |\n| Rust | `cargo horizon-mod` |\n| Lua | planned \\| soon |\n\nAfter."); + assert.equal( + html, + '
' + + "
Way inStatus
Rustcargo horizon-mod
Luaplanned | soon
\n

After.

", + ); +}); + +test("a bar inside a code span stays in its cell", () => { + assert.match(markdown("| a | b |\n|---|---|\n| `x | y` | z |"), /x \| y<\/code><\/td>z<\/td>/); +}); + +test("rows without a rule line are a paragraph", () => { + assert.equal(markdown("| a | b |\n| c | d |"), "

| a | b | | c | d |

"); +}); + +test("a link whose label is code keeps it", () => { + assert.equal(markdown("See [`AGENTS.md`](/docs/agents).", { site: true }), '

See AGENTS.md.

'); +}); diff --git a/website/src/style.css b/website/src/style.css index 4ce91791d..0279c38aa 100644 --- a/website/src/style.css +++ b/website/src/style.css @@ -687,6 +687,10 @@ code { border-radius: 0; background: var(--well); box-shadow: 0 0 0 1px var(--ou .bench-table td.num { font-variant-numeric: tabular-nums; white-space: nowrap; } .bench-table td.wins { color: var(--ink); font-weight: 600; } .bench-table td.vs { font-size: var(--text-caption); white-space: nowrap; } +.md-table { width: 100%; border-collapse: collapse; font-size: var(--text-ui); } +.md-table th, .md-table td { padding: 8px 12px 8px 0; text-align: left; border-bottom: 1px solid var(--rule); vertical-align: baseline; } +.md-table th { font-weight: 500; color: var(--ink); } +.md-table td code, .md-table th code { overflow-wrap: anywhere; } .vs-horizon { color: var(--success); } .vs-java { color: var(--danger); } .vs-tie, .vs-none { color: var(--muted); }