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/<page> 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/<page> 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 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 15:07:49 +01:00
parent bd591f9857
commit 4a9ca29887
13 changed files with 117 additions and 20 deletions
+2 -1
View File
@@ -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`).
+4
View File
@@ -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/<page> 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/* {
+7 -2
View File
@@ -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/<slug>#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/<page>` (`/docs/api/<page>`), 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
+27 -7
View File
@@ -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/<slug>.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/<page>` (/docs/api/<page>). 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(/^<!--[\s\S]*?-->\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 ? `<a class="docs-pager-${rel}" href="${d.path}"><span>${rel === "next" ? "Next" : "Previous"}</span>${escape(d.title)}</a>` : "");
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);
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+2 -1
View File
@@ -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"] }
]
+1 -1
View File
@@ -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": "/",
+5 -1
View File
@@ -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/<page> are .html files, as the Caddyfile rewrites them.
// /privacy, /docs/<page> and /docs/api/<page> are .html files, as the Caddyfile rewrites them.
if (!extname(path)) path += ".html";
let file = join(root, path);
let status = 200;
+1 -1
View File
@@ -46,7 +46,7 @@
<nav class="docs-pager" aria-label="Next and previous pages">
{{DOC_PAGER}}
</nav>
<p class="docs-edit"><a href="https://github.com/ludovic111/horizon/blob/main/website/docs/{{DOC_FILE}}">Edit this page on GitHub</a> · Spotted something wrong? <a href="https://github.com/ludovic111/horizon/issues">Open an issue</a> or ask on <a href="{{DISCORD}}">Discord</a>.</p>
<p class="docs-edit"><a href="https://github.com/ludovic111/horizon/blob/main/{{DOC_FILE}}">Edit this page on GitHub</a> · Spotted something wrong? <a href="https://github.com/ludovic111/horizon/issues">Open an issue</a> or ask on <a href="{{DISCORD}}">Discord</a>.</p>
<p class="disclaimer">Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.</p>
</main>
</div>
+36 -3
View File
@@ -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 ? `<a href="${escape(target)}">${body}</a>` : body;
});
return out.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${escape(codes[i])}</code>`);
}
// 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) => `<tr>${cells(line).map((c) => `<${tag}>${inline(c, site)}</${tag}>`).join("")}</tr>`;
let i = start + 2;
const body = [];
while (i < lines.length && ROW.test(lines[i])) body.push(row(lines[i++], "td"));
return [`<div class="table-wrap"><table class="md-table"><thead>${row(lines[start], "th")}</thead><tbody>${body.join("")}</tbody></table></div>`, 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("<hr>");
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);
+25
View File
@@ -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,
'<div class="table-wrap"><table class="md-table"><thead><tr><th>Way in</th><th>Status</th></tr></thead>' +
"<tbody><tr><td>Rust</td><td><code>cargo horizon-mod</code></td></tr><tr><td>Lua</td><td>planned | soon</td></tr></tbody></table></div>\n<p>After.</p>",
);
});
test("a bar inside a code span stays in its cell", () => {
assert.match(markdown("| a | b |\n|---|---|\n| `x | y` | z |"), /<td><code>x \| y<\/code><\/td><td>z<\/td>/);
});
test("rows without a rule line are a paragraph", () => {
assert.equal(markdown("| a | b |\n| c | d |"), "<p>| a | b | | c | d |</p>");
});
test("a link whose label is code keeps it", () => {
assert.equal(markdown("See [`AGENTS.md`](/docs/agents).", { site: true }), '<p>See <a href="/docs/agents"><code>AGENTS.md</code></a>.</p>');
});
+4
View File
@@ -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); }