@ascribed/astro 0.2.1-next.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascribed/astro",
-  "version": "0.2.1-next.9",
+  "version": "0.3.0",
   "description": "The Astro integration for Ascribe.",
   "type": "module",
   "license": "MPL-2.0",
@@ -12,10 +12,17 @@
   "homepage": "https://github.com/ascribed-dev/ascribe/tree/main/packages/astro#readme",
   "bugs": "https://github.com/ascribed-dev/ascribe/issues",
   "sideEffects": false,
+  "bin": {
+    "ascribe-astro": "./dist/cli.js"
+  },
   "files": [
     "dist",
+    "starter",
     "src/Elements.astro",
-    "src/Availability.astro"
+    "src/Availability.astro",
+    "src/Permalink.astro",
+    "src/MissingPermalink.astro",
+    "src/Head.astro"
   ],
   "exports": {
     ".": {
@@ -32,30 +39,47 @@
     },
     "./Elements.astro": "./src/Elements.astro",
     "./Availability.astro": "./src/Availability.astro",
+    "./MissingPermalink.astro": "./src/MissingPermalink.astro",
+    "./Head.astro": "./src/Head.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.9",
-    "@ascribed/elements": "0.2.1-next.9",
-    "@ascribed/review": "0.2.1-next.9",
+    "@ascribed/cli": "0.3.0",
+    "@ascribed/elements": "0.3.0",
+    "@ascribed/review": "0.3.0",
+    "github-slugger": "^2.0.0",
     "property-information": "^7.2.0",
     "smol-toml": "^1.9.0"
   },
   "peerDependencies": {
-    "astro": "^7.3.5"
+    "@types/hast": "^3.0.0",
+    "astro": "^7.3.5",
+    "satteri": "^0.10.3"
+  },
+  "peerDependenciesMeta": {
+    "@types/hast": {
+      "optional": true
+    },
+    "satteri": {
+      "optional": true
+    }
   },
   "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",
@@ -68,7 +92,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "52da4c48b9cb985c8e97d926aafa4041fc47f2eb",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",

package/src/Head.astro

@@ -0,0 +1,58 @@
+---
+// Everything a page's head says about the page, from its record in the
+// build's `_ascribe/pages.json`: its `<title>` and description, its canonical
+// link, `<meta name="robots">` (`noindex` when it isn't listed, `nosnippet`
+// when it's listed and not to be quoted), a link to its Markdown version when
+// the build publishes one and the page is offered, the Open Graph tags a link
+// preview reads, and its breadcrumbs as structured data. Each comes from the
+// record, as the sitemap and `llms.txt` do, so none can disagree with them. A
+// layout includes it in `<head>`, given the page's collection entry:
+//
+//   <Head
+//     entry={entry}
+//     title={(page, record) => (record.route === "/" ? "Loom" : `${page} · Loom`)}
+//     name="Loom"
+//     card={{ src: "/social-card.png", alt: "Loom's docs", width: 1200, height: 630 }}
+//   />
+//
+// What the site knows and the record doesn't is given by property: `title`,
+// a function from the page's title and its record, which has its route, to
+// the whole title; `name`, the site's name, for `og:site_name` and, on the
+// page at the host's root, the site-name structured data; and `card`, the
+// page's social card. The layout keeps the character set, the viewport,
+// icons, theme colors, and styles. A page with no record, such as an Astro
+// page of the site's own, gets nothing: it writes its own head.
+import { headTags, pageRecord, scriptJson, type Card, type PageRecord } from "@ascribed/astro/content";
+
+interface Props {
+  /** The page's collection entry, or `undefined` for a page that has none. */
+  entry?: { filePath?: string | undefined; data?: unknown } | undefined;
+  /** The whole title, from the page's title and its record. Default: the page's title. */
+  title?: (title: string, record: PageRecord) => string;
+  /** The site's name. */
+  name?: string;
+  /** The page's social card. Without one, no image tags. */
+  card?: Card;
+}
+
+const { entry, title, name, card } = Astro.props;
+const record = entry === undefined ? undefined : pageRecord(entry);
+const tags =
+  record === undefined
+    ? []
+    : headTags(record, { title, name, card, address: Astro.site ?? Astro.url });
+---
+
+{
+  tags.map((tag) =>
+    tag.tag === "title" ? (
+      <title>{tag.text}</title>
+    ) : tag.tag === "meta" ? (
+      <meta {...tag.attributes} />
+    ) : tag.tag === "link" ? (
+      <link {...tag.attributes} />
+    ) : (
+      <script is:inline type="application/ld+json" set:html={scriptJson(tag.json)} />
+    ),
+  )
+}

package/src/MissingPermalink.astro

@@ -0,0 +1,59 @@
+---
+// 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: by default the root of the project whose
+// permalinks it explains, which with several projects is the first that has
+// any. Children replace its last paragraph, which offers the home page and
+// searching.
+import { home as root, permalinks } from "virtual:ascribe/site";
+import { servedList } from "@ascribed/astro/permalinks";
+
+interface Props {
+  home?: string;
+}
+
+const served = servedList(permalinks);
+const { home = served?.home ?? root } = Astro.props;
+const path = served?.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,78 @@
+---
+// 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: the root of the project whose list named it.
+import { home as root, permalinks } from "virtual:ascribe/site";
+import { forwardingPaths, type Forwarding } from "@ascribed/astro/permalinks";
+
+export function getStaticPaths() {
+  return forwardingPaths(permalinks);
+}
+
+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 home = ("reason" in props ? props.home : undefined) ?? root;
+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>

package/starter/src/content.config.ts

@@ -0,0 +1,8 @@
+import { defineCollection } from "astro:content";
+import { ascribeCollection } from "@ascribed/astro/content";
+// Generated by `ascribe build --emit site`; the integration runs it first.
+import { schema } from "../.ascribe/build/site/site/_ascribe/schema.ts";
+
+export const collections = {
+  docs: defineCollection(ascribeCollection({ schema })),
+};

package/starter/src/layouts/Docs.astro

@@ -0,0 +1,87 @@
+---
+import { getCollection, type CollectionEntry } from "astro:content";
+import type { ComponentProps } from "astro/types";
+import Availability from "@ascribed/astro/Availability.astro";
+import Elements from "@ascribed/astro/Elements.astro";
+// Everything the head says about the page, from its record.
+import Head from "@ascribed/astro/Head.astro";
+import { sidebar } from "@ascribed/astro/content";
+import { nav } from "../nav.ts";
+
+interface Props {
+  entry: CollectionEntry<"docs">;
+  headings: { depth: number; slug: string; text: string }[];
+}
+
+/**
+ * What the layout reads of a page's frontmatter: `title`, which every content
+ * type has, and what a type may have. `title` is plain text; `formatted.title`
+ * is the title as HTML, with its code spans as <code>, when the content model
+ * sets `inline = "code"` on `title`.
+ */
+interface Page {
+  title: string;
+  available?: ComponentProps<typeof Availability>["available"];
+  formatted?: { title?: string };
+}
+
+const { entry, headings } = Astro.props;
+const page = (of: CollectionEntry<"docs">) => of.data as Page;
+/** A page's title as HTML: its formatted form, or its plain text escaped. */
+const titleHtml = (of: CollectionEntry<"docs">) =>
+  page(of).formatted?.title ??
+  page(of).title.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const { available } = page(entry);
+// The sidebar: src/nav.ts's groups, each page with its address. The build
+// fails when the list leaves out a page, or names one that doesn't exist.
+const groups = sidebar(nav, await getCollection("docs"));
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <Head entry={entry} />
+    <Elements />
+  </head>
+  <body>
+    <nav aria-label="Docs">
+      {
+        groups.map((group) => (
+          <section>
+            <h2>{group.label}</h2>
+            <ul>
+              {group.pages.map((item) => (
+                <li>
+                  <a
+                    href={item.href}
+                    aria-current={item.entry.id === entry.id ? "page" : undefined}
+                  >
+                    <Fragment set:html={titleHtml(item.entry)} />
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))
+      }
+    </nav>
+    <main>
+      <h1 set:html={titleHtml(entry)} />
+      <Availability available={available} />
+      <nav aria-label="On this page">
+        <ul>
+          {
+            headings.map((heading) => (
+              <li data-depth={heading.depth}>
+                <a href={`#${heading.slug}`}>{heading.text}</a>
+              </li>
+            ))
+          }
+        </ul>
+      </nav>
+      <article><slot /></article>
+    </main>
+  </body>
+</html>

package/starter/src/nav.ts

@@ -0,0 +1,13 @@
+// The sidebar's list: its groups, in order, each with its pages' source files,
+// relative to the content root. `npx @ascribed/astro init` wrote it from the
+// pages there were then; it's yours to reorder, relabel, and add to. Ascribe's
+// content model has no page order or grouping yet, so the site keeps the list,
+// and the layout's `sidebar()` keeps it complete: the build fails on a page the
+// list leaves out, and on a file it names that isn't a page.
+import type { NavGroup } from "@ascribed/astro/content";
+
+export const nav: NavGroup[] = [
+  { label: "Start", pages: ["index.md"] },
+  { label: "Guides", pages: ["Guides/My Setup.md"] },
+  { label: "Reference", pages: ["Reference/Options.md"] },
+];

package/starter/src/pages/[...slug].astro

@@ -0,0 +1,20 @@
+---
+import { getCollection, render } from "astro:content";
+import Docs from "../layouts/Docs.astro";
+
+// A page's route is the base path plus its entry id, and the root page (id
+// `index`) is at the base path itself: what Ascribe's router computes for
+// every link it writes.
+export async function getStaticPaths() {
+  const entries = await getCollection("docs");
+  return entries.map((entry) => ({
+    params: { slug: entry.id === "index" ? undefined : entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content, headings } = await render(entry);
+---
+
+<Docs entry={entry} headings={headings}><Content /></Docs>