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); }