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:
+2
-1
@@ -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`).
|
||||
|
||||
@@ -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
@@ -77,8 +77,13 @@ mark merged-but-unreleased things "next release". `{{HARNESSES}}` and `{{PERCENT
|
||||
the README. A line holding only `` 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
@@ -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);
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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"] }
|
||||
]
|
||||
|
||||
@@ -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
@@ -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;
|
||||
|
||||
@@ -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
@@ -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);
|
||||
|
||||
@@ -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>');
|
||||
});
|
||||
@@ -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); }
|
||||
|
||||
Reference in New Issue
Block a user