docs: apply the site base to the safety manual's links

Astro doesn't apply `base` to markdown links, so writing them from the
site root broke the deployed build, which serves the manual under a
versioned path: link validation rejected all 13 as pointing nowhere.

Add the base in a remark plugin instead, ahead of the validator's rehype
pass, and let every source keep writing links from the site root.

Author: tronical

docs/common/src/utils/remark-base-links.mjs

@@ -0,0 +1,41 @@
+// Copyright © SixtyFPS GmbH <info@slint.dev>
+// SPDX-License-Identifier: MIT
+
+// Prefix the site base to the internal links of a page. Astro doesn't apply
+// `base` to markdown links, so a site served under a path would need every
+// link to spell that path out. Sources instead write links from the site root
+// -- `/language/properties/` -- and this adds the base, in one place, at build
+// time. That keeps the sources free of the deployment layout, which the
+// release job rewrites per version.
+//
+// It matters for more than the output: starlight-links-validator resolves a
+// link against the deployed path, so an unprefixed link fails validation as a
+// link to an unknown page. Remark runs before the validator's rehype pass, so
+// what gets checked is the prefixed link.
+
+/** Rewrite the `url` of every link and link definition in the tree. */
+function walk(node, fn) {
+    if (node.type === "link" || node.type === "definition") {
+        fn(node);
+    }
+    for (const child of node.children ?? []) {
+        walk(child, fn);
+    }
+}
+
+export default function remarkBaseLinks({ base = "/" } = {}) {
+    const prefix = base.replace(/\/+$/, "");
+    // Served at the root, so the links already read as they should.
+    if (prefix === "") {
+        return () => {};
+    }
+    return (tree) => {
+        walk(tree, (node) => {
+            // A protocol-relative URL also starts with a slash and leaves the
+            // site, so it isn't ours to rewrite.
+            if (node.url?.startsWith("/") && !node.url.startsWith("//")) {
+                node.url = `${prefix}${node.url}`;
+            }
+        });
+    };
+}

docs/safety/astro.config.mjs

@@ -15,6 +15,7 @@ import {
     SAFETY_DOCS_BASE_PATH,
 } from "./src/safety-site-config.mjs";
 import rehypeSlsIds from "@slint/common-files/src/utils/rehype-sls-ids.mjs";
+import remarkBaseLinks from "@slint/common-files/src/utils/remark-base-links.mjs";
 
 const _safetyOrigin = String(SAFETY_DOCS_BASE_URL).replace(/\/+$/, "");
 const _safetyAtRoot = SAFETY_DOCS_BASE_PATH === "/";
@@ -33,6 +34,7 @@ export default defineConfig({
     markdown: {
         // Only SC-covered content reaches this site's generated reference, so
         // every paragraph of it carries a traceability id.
+        remarkPlugins: [[remarkBaseLinks, { base: _safetyBase ?? "/" }]],
         rehypePlugins: [
             rehypeExternalLinksSlint,
             [rehypeSlsIds, { referenceRequiresIds: true }],

docs/safety/scripts/sync-language-spec.mjs

@@ -17,10 +17,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { SAFETY_DOCS_BASE_PATH } from "../src/safety-site-config.mjs";
-
-// The path this site is served under, with a trailing `/`.
-const BASE = `/${SAFETY_DOCS_BASE_PATH.replace(/^\/+|\/+$/g, "")}/`.replace("//", "/");
 
 // Links that leave the specification directory: canonical (docs/astro) form
 // on the left, safety-manual form on the right.
@@ -42,11 +38,12 @@ function stripNotInSC(content) {
     return content.replace(/<NotInSC>[\s\S]*?<\/NotInSC>\n?/g, "");
 }
 
-// Rewrite the markdown links of a page served at `pageUrl` from the site base,
-// so that starlight-links-validator checks them. Resolving against the page's
-// own URL keeps the sources readable: they stay relative, and only the copies
-// this script writes carry the site's layout.
-function linksFromBase(content, pageUrl) {
+// Rewrite the markdown links of a page served at `pageUrl` from the site root,
+// so that starlight-links-validator checks them: it skips relative links
+// rather than resolving them. Resolving against the page's own URL keeps the
+// sources readable, since they stay relative. remark-base-links.mjs adds the
+// base at build time.
+function linksFromRoot(content, pageUrl) {
     return content.replace(/\]\((\.\.?\/[^)]*)\)/g, (_, url) => {
         const resolved = new URL(url, `https://slint.dev${pageUrl}`);
         return `](${resolved.pathname}${resolved.hash})`;
@@ -109,7 +106,7 @@ for (const entry of readdirSync(source)) {
     for (const [from, to] of LINK_MAP) {
         content = content.replaceAll(from, to);
     }
-    content = linksFromBase(stripNotInSC(content), pageUrl(`${BASE}language/`, entry));
+    content = linksFromRoot(stripNotInSC(content), pageUrl("/language/", entry));
     const targetFile = join(target, entry);
     if (!existsSync(targetFile) || readFileSync(targetFile, "utf-8") !== content) {
         writeFileSync(targetFile, content);
@@ -130,10 +127,7 @@ syncDir(
     join(here, "../src/content/docs/reference/property-types"),
     (content) => !isNotInSC(content),
     (content, entry) =>
-        linksFromBase(
-            stripNotInSC(content),
-            pageUrl(`${BASE}reference/property-types/`, entry),
-        ),
+        linksFromRoot(stripNotInSC(content), pageUrl("/reference/property-types/", entry)),
 );
 
 console.log(`Synced language specification from ${source}`);

docs/slint-doc-generator/traceability.rs

@@ -53,21 +53,17 @@ const SAFETY_DOCS_EXCLUDE: &[&str] = &["generated", "language"];
 /// [`Config::qualification_plan_dir`], the section it belongs to.
 const MATRIX_FILE: &str = "traceability-matrix.mdx";
 
-/// Where the safety manual declares the path it is served under. The matrix
-/// links from that base rather than relatively, because
-/// starlight-links-validator skips relative links: a relative one here would
-/// go unchecked, and could rot into a dead anchor unnoticed.
-const SAFETY_SITE_CONFIG: &str = "docs/safety/src/safety-site-config.mjs";
-
 const REPO_URL: &str = env!("CARGO_PKG_REPOSITORY");
 
 struct SpecPage {
     /// Repository-relative path with `/` separators, for error messages.
     file: String,
     /// From the frontmatter.
     title: String,
-    /// URL of the page from the site base, for linking its anchors from the
-    /// matrix. See [`SAFETY_SITE_CONFIG`] for why it isn't relative.
+    /// URL of the page from the site root, for linking its anchors from the
+    /// matrix. Not relative, because starlight-links-validator skips relative
+    /// links: one here would go unchecked and could rot into a dead anchor.
+    /// remark-base-links.mjs adds the site base at build time.
     base: String,
     /// The specification index heads its section; every other page nests
     /// under one.
@@ -104,11 +100,10 @@ impl TestRef {
 
 pub fn generate(cfg: &Config) -> Result<(), Box<dyn std::error::Error>> {
     let root = crate::root_dir();
-    let base = safety_base(&root)?;
-    let mut spec_pages = scan_spec_pages(&root.join(SPEC_DIR), &base)?;
-    spec_pages.extend(scan_property_type_pages(&root, &base)?);
-    let reference_pages = scan_reference_pages(cfg, &root, &base)?;
-    let safety_pages = scan_safety_pages(&root, &base)?;
+    let mut spec_pages = scan_spec_pages(&root.join(SPEC_DIR))?;
+    spec_pages.extend(scan_property_type_pages(&root)?);
+    let reference_pages = scan_reference_pages(cfg, &root)?;
+    let safety_pages = scan_safety_pages(&root)?;
 
     let mut refs = Vec::new();
     for kind in TEST_ROOTS {
@@ -132,7 +127,7 @@ pub fn generate(cfg: &Config) -> Result<(), Box<dyn std::error::Error>> {
         }
     }
 
-    write_matrix(cfg, &root, &base, &spec_pages, &reference_pages, &safety_pages, &tests_by_id)
+    write_matrix(cfg, &root, &spec_pages, &reference_pages, &safety_pages, &tests_by_id)
 }
 
 /// Validate the parsed pages and test references, returning one message per
@@ -266,19 +261,6 @@ fn parse_spec_page(file: &str, text: &str) -> (SpecPage, Option<String>) {
     (page, slug)
 }
 
-/// The path the safety manual is served under, with leading and trailing `/`.
-fn safety_base(repo_root: &Path) -> Result<String, Box<dyn std::error::Error>> {
-    let path = repo_root.join(SAFETY_SITE_CONFIG);
-    let text = std::fs::read_to_string(&path).context(format!("error reading {path:?}"))?;
-    let value = text
-        .lines()
-        .find_map(|line| line.trim().strip_prefix("export const SAFETY_DOCS_BASE_PATH ="))
-        .map(|value| value.trim().trim_end_matches(';').trim().trim_matches('"'))
-        .ok_or_else(|| anyhow::anyhow!("{SAFETY_SITE_CONFIG}: no SAFETY_DOCS_BASE_PATH"))?;
-    let trimmed = value.trim_matches('/');
-    Ok(if trimmed.is_empty() { "/".to_string() } else { format!("/{trimmed}/") })
-}
-
 /// Repository-relative path with `/` separators.
 fn repo_relative(path: &Path, repo_root: &Path) -> String {
     let relative = path.strip_prefix(repo_root).unwrap_or(path).to_string_lossy().into_owned();
@@ -289,7 +271,7 @@ fn repo_relative(path: &Path, repo_root: &Path) -> String {
     }
 }
 
-fn scan_spec_pages(dir: &Path, base: &str) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
+fn scan_spec_pages(dir: &Path) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
     let mut paths: Vec<std::path::PathBuf> = std::fs::read_dir(dir)
         .context(format!("error reading {dir:?}"))?
         .filter_map(|e| Some(e.ok()?.path()))
@@ -311,11 +293,8 @@ fn scan_spec_pages(dir: &Path, base: &str) -> Result<Vec<SpecPage>, Box<dyn std:
         }
         // The index page is served at the root of the specification.
         page.top_level = stem == "index";
-        page.base = if page.top_level {
-            format!("{base}language/")
-        } else {
-            format!("{base}language/{stem}/")
-        };
+        page.base =
+            if page.top_level { format!("/language/") } else { format!("/language/{stem}/") };
         if !page.draft {
             pages.push(page);
         }
@@ -327,10 +306,7 @@ fn scan_spec_pages(dir: &Path, base: &str) -> Result<Vec<SpecPage>, Box<dyn std:
 /// their anchors. Pages marked `notInSC: true` cover the full language only, so
 /// they carry no requirements; the rest are served in the safety manual under
 /// `reference/property-types/`.
-fn scan_property_type_pages(
-    root: &Path,
-    base: &str,
-) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
+fn scan_property_type_pages(root: &Path) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
     let dir = root.join(PROPERTY_TYPES_DIR);
     let mut paths: Vec<std::path::PathBuf> = std::fs::read_dir(&dir)
         .context(format!("error reading {dir:?}"))?
@@ -348,7 +324,7 @@ fn scan_property_type_pages(
         if page.not_in_sc || page.anchors.is_empty() || page.draft {
             continue;
         }
-        page.base = format!("{base}reference/property-types/{stem}/");
+        page.base = format!("/reference/property-types/{stem}/");
         pages.push(page);
     }
     Ok(pages)
@@ -359,7 +335,6 @@ fn scan_property_type_pages(
 fn scan_reference_pages(
     cfg: &Config,
     repo_root: &Path,
-    base: &str,
 ) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
     let mut pages = Vec::new();
     for entry in walkdir::WalkDir::new(cfg.reference_dir()).sort_by_file_name() {
@@ -379,7 +354,7 @@ fn scan_reference_pages(
         // couldn't link to the anchors it just found.
         let slug = slug
             .ok_or_else(|| anyhow::anyhow!("{file}: generated page carries anchors but no slug"))?;
-        page.base = format!("{base}{slug}/");
+        page.base = format!("/{slug}/");
         pages.push(page);
     }
     Ok(pages)
@@ -394,10 +369,7 @@ fn safety_page_slug(relative: &str) -> &str {
 }
 
 /// Parse the handwritten safety-manual pages for their anchors.
-fn scan_safety_pages(
-    repo_root: &Path,
-    base: &str,
-) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
+fn scan_safety_pages(repo_root: &Path) -> Result<Vec<SpecPage>, Box<dyn std::error::Error>> {
     let dir = repo_root.join(SAFETY_DOCS_DIR);
     let mut pages = Vec::new();
     for entry in walkdir::WalkDir::new(&dir)
@@ -428,7 +400,7 @@ fn scan_safety_pages(
         }
         let relative = repo_relative(path, &dir);
         let slug = slug.unwrap_or_else(|| safety_page_slug(&relative).to_string());
-        page.base = format!("{base}{slug}/");
+        page.base = format!("/{slug}/");
         pages.push(page);
     }
     Ok(pages)
@@ -484,7 +456,6 @@ fn git_head(repo_root: &Path) -> String {
 fn write_matrix(
     cfg: &Config,
     repo_root: &Path,
-    base: &str,
     spec_pages: &[SpecPage],
     reference_pages: &[SpecPage],
     safety_pages: &[SpecPage],
@@ -512,7 +483,7 @@ description: Mapping between the requirement paragraphs of the Language Specific
 slug: qualification-plan/traceability-matrix
 ---
 
-Each requirement paragraph in the [Language Specification]({base}language/), the [SC API Reference]({base}reference/), and the other chapters of this manual carries a unique identifier,
+Each requirement paragraph in the [Language Specification](/language/), the [SC API Reference](/reference/), and the other chapters of this manual carries a unique identifier,
 shown as a `[sls.…]` badge at the end of the paragraph.
 A test case declares which requirements it verifies by listing their identifiers in `//#sls.…` comments.
 This matrix lists every requirement paragraph with the test cases that declare it.