@ascribed/astro 0.2.1-next.11 → 0.2.1-next.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascribed/astro",
-  "version": "0.2.1-next.11",
+  "version": "0.2.1-next.13",
   "description": "The Astro integration for Ascribe.",
   "type": "module",
   "license": "MPL-2.0",
@@ -15,7 +15,9 @@
   "files": [
     "dist",
     "src/Elements.astro",
-    "src/Availability.astro"
+    "src/Availability.astro",
+    "src/Permalink.astro",
+    "src/MissingPermalink.astro"
   ],
   "exports": {
     ".": {
@@ -32,18 +34,23 @@
     },
     "./Elements.astro": "./src/Elements.astro",
     "./Availability.astro": "./src/Availability.astro",
+    "./MissingPermalink.astro": "./src/MissingPermalink.astro",
     "./content": {
       "types": "./dist/content.d.ts",
       "default": "./dist/content.js"
+    },
+    "./permalinks": {
+      "types": "./dist/permalinks.d.ts",
+      "default": "./dist/permalinks.js"
     }
   },
   "engines": {
     "node": ">=24"
   },
   "dependencies": {
-    "@ascribed/cli": "0.2.1-next.11",
-    "@ascribed/elements": "0.2.1-next.11",
-    "@ascribed/review": "0.2.1-next.11",
+    "@ascribed/cli": "0.2.1-next.13",
+    "@ascribed/elements": "0.2.1-next.13",
+    "@ascribed/review": "0.2.1-next.13",
     "property-information": "^7.2.0",
     "smol-toml": "^1.9.0"
   },
@@ -63,9 +70,9 @@
   "devDependencies": {
     "@types/hast": "^3.0.4",
     "@types/node": "^24.0.0",
-    "astro": "7.3.5",
+    "astro": "7.3.6",
     "hast-util-from-html": "^2.0.3",
-    "jsdom": "^30.1.1",
+    "jsdom": "^30.1.2",
     "rehype-raw": "^7.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
@@ -78,7 +85,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "dd64394135ff782efb8db030c81ac3b38e0f92c5",
+  "gitHead": "42f00096ceb0f91a736b6a3d485eb38a91fbcc48",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",

package/src/MissingPermalink.astro

@@ -0,0 +1,56 @@
+---
+// For a site's not-found page: on an address under the permalinks' path, it
+// says the link came from a product that expected a section of these docs
+// there, and that these docs don't have it. Anywhere else it shows nothing. A
+// static host serves one not-found page for every missing address, so its
+// script decides from the address, and without a script it stays hidden.
+//
+//   import MissingPermalink from "@ascribed/astro/MissingPermalink.astro";
+//   <MissingPermalink />
+//
+// `home` is where it sends the reader, the site's root by default. Children
+// replace its last paragraph, which offers the home page and searching.
+import { home as root, siteRoot } from "virtual:ascribe/site";
+import { readPermalinks } from "@ascribed/astro/permalinks";
+
+interface Props {
+  home?: string;
+}
+
+const { home = root } = Astro.props;
+const path = readPermalinks(siteRoot)?.path;
+---
+
+{
+  path !== undefined && (
+    <section data-permalinks={path} hidden>
+      <p>
+        This address is a permalink, <code />: a name a product links to for a section of its
+        documentation. These docs have no section by that name. The link may come from a newer or
+        older version of the product than they describe.
+      </p>
+      <slot>
+        <p>Start from the <a href={home}>home page</a>, or search the docs for what you need.</p>
+      </slot>
+    </section>
+  )
+}
+
+<script>
+  for (const section of document.querySelectorAll<HTMLElement>("section[data-permalinks]")) {
+    const path = section.dataset["permalinks"] ?? "";
+    let address: string;
+    try {
+      address = decodeURIComponent(location.pathname);
+    } catch {
+      continue;
+    }
+    if (!address.startsWith(path)) continue;
+    // One segment after the path, as every permalink's address has.
+    const name = address.slice(path.length).replace(/\/$/, "");
+    if (name === "" || name.includes("/")) continue;
+    const code = section.querySelector("code");
+    if (code !== null) code.textContent = name;
+    section.hidden = false;
+  }
+</script>

package/src/Permalink.astro

@@ -0,0 +1,77 @@
+---
+// A permalink's address: a page that sends the reader on to the heading it
+// names, wherever that is now. The integration adds it as a route at
+// `<path>[id]`, one page for each entry of the site output's
+// `_ascribe/permalinks.json`. It forwards without a script, links to the same
+// place for a browser that doesn't follow, and isn't indexed. Its script
+// first takes the reader's choices from the address's parameters
+// (`?platform=macos`), as if they'd picked those tabs, then forwards.
+//
+// A retired permalink with nowhere to lead gets a page that says what was
+// here was removed, gives the reason as its authors wrote it, as text, and
+// links to the docs' home.
+import { home, siteRoot } from "virtual:ascribe/site";
+import { forwardingPaths, type Forwarding } from "@ascribed/astro/permalinks";
+
+export function getStaticPaths() {
+  return forwardingPaths(siteRoot);
+}
+
+const props = Astro.props as Forwarding;
+const to = "to" in props ? props.to : undefined;
+const dimensions = "to" in props ? props.dimensions : {};
+const reason = "reason" in props ? props.reason : undefined;
+const canonical =
+  to === undefined || Astro.site === undefined ? to : new URL(to, Astro.site).href;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {to === undefined ? <title>Removed from these docs</title> : <title>Redirecting to {to}</title>}
+    <meta name="robots" content="noindex" />
+    {to !== undefined && <meta http-equiv="refresh" content={`0;url=${to}`} />}
+    {canonical !== undefined && <link rel="canonical" href={canonical} />}
+  </head>
+  <body>
+    {
+      to === undefined ? (
+        <main>
+          <h1>Removed from these docs</h1>
+          <p>What this link led to was removed from these docs.</p>
+          <p data-reason>{reason}</p>
+          <p>
+            <a href={home}>Go to the docs' home page</a>
+          </p>
+        </main>
+      ) : (
+        <p>
+          This link leads to <a href={to} data-dimensions={JSON.stringify(dimensions)}>{to}</a>.
+        </p>
+      )
+    }
+    <script>
+      import { choose } from "@ascribed/elements";
+
+      // A parameter that names one of the content model's dimensions, with one of
+      // its values, is the reader's choice for it. Anything else is ignored, so a
+      // product sends what it knows without asking what the docs accept.
+      const link = document.querySelector<HTMLAnchorElement>("a[data-dimensions]");
+      if (link !== null) {
+        const dimensions = JSON.parse(link.dataset["dimensions"] ?? "{}") as Record<string, string[]>;
+        const chosen = new Set<string>();
+        for (const [name, value] of new URLSearchParams(location.search)) {
+          if (chosen.has(name) || !Object.hasOwn(dimensions, name)) continue;
+          if (dimensions[name]?.includes(value)) {
+            chosen.add(name);
+            choose(name, value);
+          }
+        }
+        // Sooner than the refresh, which waits for the page to load.
+        location.replace(link.href);
+      }
+    </script>
+  </body>
+</html>