From 021c9f8a599a0c769a3a9f6794b09cb5d9c64f91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C5=ABdolfs=20O=C5=A1i=C5=86=C5=A1?= <rudolfs@osins.org>
Date: Thu, 8 Oct 2026 10:07:41 +0200
Subject: [PATCH] Link AsciiDoc cross references to their source

`xref:other.adoc[]` linked to `other.html`, which doesn't exist in the
repository, so following it showed a missing file instead.
---
 src/lib/asciidoc.ts         |  3 +++
 tests/unit/asciidoc.test.ts | 21 +++++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 tests/unit/asciidoc.test.ts

diff --git a/src/lib/asciidoc.ts b/src/lib/asciidoc.ts
index 8d3442a2a..44b8ffc5d 100644
--- a/src/lib/asciidoc.ts
+++ b/src/lib/asciidoc.ts
@@ -185,6 +185,9 @@ export async function renderAsciidoc(
         showtitle: true,
         "allow-uri-read": "",
         "cache-uri": "",
+        // Cross references to other documents link to their source files,
+        // which is what the app shows, rather than to rendered `.html` pages.
+        relfilesuffix: ".adoc",
       },
       /* eslint-enable @typescript-eslint/naming-convention */
     });
diff --git a/tests/unit/asciidoc.test.ts b/tests/unit/asciidoc.test.ts
new file mode 100644
index 000000000..9a295e047
--- /dev/null
+++ b/tests/unit/asciidoc.test.ts
@@ -0,0 +1,21 @@
+import { expect, test, vi } from "vitest";
+
+import { renderAsciidoc } from "@app/lib/asciidoc";
+
+vi.mock("@app/lib/invoke", () => ({ invoke: vi.fn() }));
+
+const source = {
+  rid: "rad:z3fpY7nttPPa6MBnAv2DccHzQJnqe",
+  sha: "a".repeat(40),
+  path: "docs/index.adoc",
+};
+
+test.each([
+  ["xref:spec.adoc[Spec]", "spec.adoc"],
+  ["xref:spec.adoc#_details[Spec]", "spec.adoc#_details"],
+  ["<<spec.adoc#,Spec>>", "spec.adoc"],
+  ["<<_details,Details>>", "#_details"],
+])("links %j to %j", async (content, href) => {
+  const html = await renderAsciidoc(content, source);
+  expect(html).toContain(`href="${href}"`);
+});