@ascribed/astro 0.4.5-next.33 → 0.4.5-next.34

package/README.md

@@ -71,7 +71,7 @@ A versioned build (`versions` in `ascribe.toml`) is one collection with every li
 
 A page's Markdown version has no head, so its rules are response headers, which each build lists in `_ascribe/headers.json`: `X-Robots-Tag` when the page isn't listed, and a canonical `Link` to the page. `astro dev` sends them. With `[consumer] host = "netlify"`, each build writes them in Netlify's format too, at `_ascribe/host/_headers`, and `astro build` merges every project's into the site's `_headers`; a site with its own `public/_headers` keeps it, and the build fails with the lines it lacks. The same setting has `astro build` write the site's `_redirects`, from the moves each project's `ascribe.addresses` records, ahead of a site's own `public/_redirects`.
 
-`npx @ascribed/astro init` writes those files into an Astro project once, as yours from then on: the collection (`src/content.config.ts`), the route (`src/pages/[...slug].astro`), and a layout that loads the elements and draws the sidebar (`src/layouts/Docs.astro`). It never writes over a file. `--project <dir>` names the folder holding `ascribe.toml`, and `--build <name>` the build, when there are several. The layout's sidebar comes from `sidebar(entries, { entry })` in `@ascribed/astro/content`: the project's navigation, in `ascribe.nav`'s order or the default one, from the build's `_ascribe/nav.json`, with no list to keep. `neighbors(entry, entries)` gives a page's previous and next in the same order, for links at its foot. A site's own list, `sidebar(entries, { nav })`, overrides the navigation: its groups, in its order, and the build fails when the list leaves out a page or names one that isn't there; `neighbors` takes it too.
+`npx @ascribed/astro init` writes those files into an Astro project once, as yours from then on: the collection (`src/content.config.ts`), the route (`src/pages/[...slug].astro`), a layout that loads the elements and draws the sidebar (`src/layouts/Docs.astro`), and the layout's stylesheet (`src/styles/docs.css`), whose colors and spaces are the element library's `--ascribe-*` properties. It never writes over a file. `--project <dir>` names the folder holding `ascribe.toml`, and `--build <name>` the build, when there are several. The layout's sidebar comes from `sidebar(entries, { entry })` in `@ascribed/astro/content`: the project's navigation, in `ascribe.nav`'s order or the default one, from the build's `_ascribe/nav.json`, with no list to keep. `neighbors(entry, entries)` gives a page's previous and next in the same order, for links at its foot. A site's own list, `sidebar(entries, { nav })`, overrides the navigation: its groups, in its order, and the build fails when the list leaves out a page or names one that isn't there; `neighbors` takes it too.
 
 The [Astro guide](https://ascribed-dev.com/go/astro-guide/) walks through a site: `ascribe.toml`, the collection, the route, and the layout. Its section's how-tos put [a home page in front of the docs](https://ascribed-dev.com/go/a-home-page-in-front-of-the-docs/), or [several projects in one site](https://ascribed-dev.com/go/several-projects-in-one-site/). The [`@ascribed/astro` reference](https://ascribed-dev.com/go/astro-reference/) has the options, the components, what the integration does in `astro build` and `astro dev`, search engines and crawlers, and [review in the site preview](https://ascribed-dev.com/go/review-in-the-site-preview/). [Review](https://ascribed-dev.com/go/review-guide/) walks through reviewing a pull request on your site.
 
@@ -100,6 +100,7 @@ The [Astro guide](https://ascribed-dev.com/go/astro-guide/) walks through a site
 | `src/Availability.astro` | A page's availability as the element library's badge |
 | `src/Versions.astro`, `src/VersionBanner.astro`, `src/versions.ts` | A versioned build's lines, from `<output-dir>/_ascribe/versions.json`, the list of the lines that have a page, and an older line's banner |
 | `src/code-titles.ts` | The Shiki transformer that shows code block titles and tested lines |
+| `src/code-languages.ts` | The Shiki transformer that gives a code block's `<code>` its language as a class |
 | `src/Permalink.astro`, `src/permalinks.ts` | The route at each permalink's address, and its pages, from the site output's `_ascribe/permalinks.json` |
 | `src/MissingPermalink.astro` | The explanation on a site's 404 page for an address under the permalinks' path that matches nothing |
 | `src/schema.ts` | Copies the generated schema inside the Astro root |

package/dist/code-languages.d.ts

@@ -0,0 +1,10 @@
+import type { AstroUserConfig } from "astro";
+type ShikiTransformer = NonNullable<NonNullable<NonNullable<AstroUserConfig["markdown"]>["shikiConfig"]>["transformers"]>[number];
+/**
+ * The language Shiki highlighted the block as, the `data-language` Astro
+ * gives its <pre>. Astro highlights a block with no language, and one in a
+ * language Shiki doesn't know, as `plaintext`, which has no class, as a block
+ * with no language has none before highlighting.
+ */
+export declare const codeLanguages: ShikiTransformer;
+export {};

package/dist/code-languages.js

@@ -0,0 +1,16 @@
+/**
+ * The language Shiki highlighted the block as, the `data-language` Astro
+ * gives its <pre>. Astro highlights a block with no language, and one in a
+ * language Shiki doesn't know, as `plaintext`, which has no class, as a block
+ * with no language has none before highlighting.
+ */
+export const codeLanguages = {
+    name: "@ascribed/astro:code-languages",
+    code(node) {
+        const lang = this.options.lang;
+        if (typeof lang !== "string" || lang === "" || lang === "plaintext")
+            return;
+        this.addClassToHast(node, `language-${lang}`);
+    },
+};
+//# sourceMappingURL=code-languages.js.map

package/dist/code-languages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-languages.js","sourceRoot":"","sources":["../src/code-languages.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C,IAAI,EAAE,gCAAgC;IACtC,IAAI,CAAC,IAAI;QACP,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,WAAW;YAAE,OAAO;QAC5E,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;CACF,CAAC","sourcesContent":["// A code block's language as a class on its <code>, `language-sh`, as\n// CommonMark renders it before Shiki highlights it. Shiki's output keeps the\n// language only in the <pre>'s `data-language`, which HTML-to-text and\n// HTML-to-Markdown converters don't read, so their fences came out with no\n// language (decision #1038, site-render contract §5.2). The integration adds\n// this Shiki transformer, so it's the same in `astro dev` and the build.\nimport type { AstroUserConfig } from \"astro\";\n\ntype ShikiTransformer = NonNullable<\n  NonNullable<NonNullable<AstroUserConfig[\"markdown\"]>[\"shikiConfig\"]>[\"transformers\"]\n>[number];\n\n/**\n * The language Shiki highlighted the block as, the `data-language` Astro\n * gives its <pre>. Astro highlights a block with no language, and one in a\n * language Shiki doesn't know, as `plaintext`, which has no class, as a block\n * with no language has none before highlighting.\n */\nexport const codeLanguages: ShikiTransformer = {\n  name: \"@ascribed/astro:code-languages\",\n  code(node) {\n    const lang = this.options.lang;\n    if (typeof lang !== \"string\" || lang === \"\" || lang === \"plaintext\") return;\n    this.addClassToHast(node, `language-${lang}`);\n  },\n};\n"]}

package/dist/code-titles.js

@@ -1,12 +1,56 @@
 import { CLASS_CODE_TESTED } from "./names.js";
 /**
- * The value of `key="…"` in a code block's meta, if it has one. The meta has
- * its Markdown escapes taken off (`title="say \"hi\""` arrives as
- * `title="say "hi""`), so the value ends at a quote followed by a space or
- * the end, and a quote inside it survives.
+ * The value of the first `key=value` pair in a code block's meta, the info
+ * string past its language, when it isn't empty. The meta has its Markdown
+ * escapes taken off, and is read as SPEC §3.3.1 reads an info string, as
+ * `ascribe_core::info_string` does: words parted by spaces and tabs, a pair's
+ * value a token or a quoted string in which `\"` and `\\` escape, and a pair
+ * followed by a space, a tab, or the end. Any other word isn't a pair.
  */
 function metaValue(meta, key) {
-    return new RegExp(`(?:^|\\s)${key}="(.*?)"(?=\\s|$)`).exec(meta)?.[1] || undefined;
+    let i = 0;
+    while (i < meta.length) {
+        if (meta[i] === " " || meta[i] === "\t") {
+            i += 1;
+            continue;
+        }
+        const pair = /^([a-z][a-z0-9-]*)=/.exec(meta.slice(i));
+        let end = wordEnd(meta, i);
+        let value;
+        if (pair !== null) {
+            let j = i + pair[0].length;
+            if (meta[j] === '"') {
+                let text = "";
+                j += 1;
+                while (j < meta.length && meta[j] !== '"') {
+                    if (meta[j] === "\\" && (meta[j + 1] === '"' || meta[j + 1] === "\\"))
+                        j += 1;
+                    text += meta[j];
+                    j += 1;
+                }
+                if (j < meta.length && (j + 1 === meta.length || isSpace(meta[j + 1]))) {
+                    value = text;
+                    end = j + 1;
+                }
+            }
+            else if (j < end && !meta.slice(j, end).includes('"')) {
+                value = meta.slice(j, end);
+            }
+        }
+        if (value !== undefined && pair?.[1] === key)
+            return value || undefined;
+        i = end;
+    }
+    return undefined;
+}
+function isSpace(c) {
+    return c === " " || c === "\t";
+}
+function wordEnd(text, from) {
+    let i = from;
+    while (i < text.length && !isSpace(text[i]))
+        i += 1;
+    return i;
 }
 /** The `title="…"` in a code block's meta, if it has one. */
 export function codeTitle(meta) {

package/dist/code-titles.js.map

@@ -1 +1 @@
-{"version":3,"file":"code-titles.js","sourceRoot":"","sources":["../src/code-titles.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAM/C;;;;;GAKG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,GAAW;IAC1C,OAAO,IAAI,MAAM,CAAC,YAAY,GAAG,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AACrF,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAqB;IAC3D,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,iBAAiB,CAAC,EAAE;YAC9C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,QAAQ;QACjB,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,YAAY,CAAC,EAAE;QACzC,QAAQ,EAAE;YACR,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE;YAC7E,KAAK;SACN;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C,IAAI,EAAE,6BAA6B;IACnC,IAAI,CAAC,IAAI;QACP,MAAM,IAAI,GAAI,IAAI,CAAC,OAAO,CAAC,IAAuC,EAAE,KAAK,IAAI,EAAE,CAAC;QAChF,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;QAClE,gEAAgE;QAChE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO;QAC1D,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;CACF,CAAC","sourcesContent":["// A code block's caption, shown above it: its title, and what a tested\n// example was tested with. A `@snippet`'s title is in the code block's info\n// string, as `title=\"…\"`, and its tested line as `tested=\"…\"` (SPEC §4.8), and\n// Astro's own code highlighting ignores both (issue #106), so the integration\n// adds this Shiki transformer, which puts such a block in a\n// <figure class=\"code-title\"> with a <figcaption>: the title, then the tested\n// line in a <div class=\"ascribe-code-tested\"> of its own, whose \"Tested with\"\n// lead-in is the element library's stylesheet's (site-render contract §5.1).\nimport type { AstroUserConfig } from \"astro\";\nimport type { Element, ElementContent } from \"hast\";\nimport { CLASS_CODE_TESTED } from \"./names.js\";\n\ntype ShikiTransformer = NonNullable<\n  NonNullable<NonNullable<AstroUserConfig[\"markdown\"]>[\"shikiConfig\"]>[\"transformers\"]\n>[number];\n\n/**\n * The value of `key=\"…\"` in a code block's meta, if it has one. The meta has\n * its Markdown escapes taken off (`title=\"say \\\"hi\\\"\"` arrives as\n * `title=\"say \"hi\"\"`), so the value ends at a quote followed by a space or\n * the end, and a quote inside it survives.\n */\nfunction metaValue(meta: string, key: string): string | undefined {\n  return new RegExp(`(?:^|\\\\s)${key}=\"(.*?)\"(?=\\\\s|$)`).exec(meta)?.[1] || undefined;\n}\n\n/** The `title=\"…\"` in a code block's meta, if it has one. */\nexport function codeTitle(meta: string): string | undefined {\n  return metaValue(meta, \"title\");\n}\n\n/** The `tested=\"…\"` in a code block's meta, if it has one. */\nexport function codeTested(meta: string): string | undefined {\n  return metaValue(meta, \"tested\");\n}\n\n/**\n * The block, in a figure whose caption holds its title and its tested line;\n * `undefined` when it has neither.\n */\nexport function captioned(meta: string, block: ElementContent): Element | undefined {\n  const title = codeTitle(meta);\n  const tested = codeTested(meta);\n  if (title === undefined && tested === undefined) return undefined;\n  const caption: ElementContent[] = [];\n  if (title !== undefined) caption.push({ type: \"text\", value: title });\n  if (tested !== undefined) {\n    caption.push({\n      type: \"element\",\n      tagName: \"div\",\n      properties: { className: [CLASS_CODE_TESTED] },\n      children: [{ type: \"text\", value: tested }],\n    });\n  }\n  return {\n    type: \"element\",\n    tagName: \"figure\",\n    properties: { className: [\"code-title\"] },\n    children: [\n      { type: \"element\", tagName: \"figcaption\", properties: {}, children: caption },\n      block,\n    ],\n  };\n}\n\nexport const codeTitles: ShikiTransformer = {\n  name: \"@ascribed/astro:code-titles\",\n  root(root) {\n    const meta = (this.options.meta as { __raw?: string } | undefined)?.__raw ?? \"\";\n    const pre = root.children.find((node) => node.type === \"element\");\n    // A site's own transformer may have put it in a figure already.\n    if (pre === undefined || pre.tagName === \"figure\") return;\n    const figure = captioned(meta, pre);\n    if (figure !== undefined) root.children = [figure];\n  },\n};\n"]}
+{"version":3,"file":"code-titles.js","sourceRoot":"","sources":["../src/code-titles.ts"],"names":[],"mappings":"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","sourcesContent":["// A code block's caption, shown above it: its title, and what a tested\n// example was tested with. A `@snippet`'s title is in the code block's info\n// string, as `title=\"…\"`, and its tested line as `tested=\"…\"` (SPEC §4.8), and\n// Astro's own code highlighting ignores both (issue #106), so the integration\n// adds this Shiki transformer, which puts such a block in a\n// <figure class=\"code-title\"> with a <figcaption>: the title, then the tested\n// line in a <div class=\"ascribe-code-tested\"> of its own, whose \"Tested with\"\n// lead-in is the element library's stylesheet's (site-render contract §5.1).\nimport type { AstroUserConfig } from \"astro\";\nimport type { Element, ElementContent } from \"hast\";\nimport { CLASS_CODE_TESTED } from \"./names.js\";\n\ntype ShikiTransformer = NonNullable<\n  NonNullable<NonNullable<AstroUserConfig[\"markdown\"]>[\"shikiConfig\"]>[\"transformers\"]\n>[number];\n\n/**\n * The value of the first `key=value` pair in a code block's meta, the info\n * string past its language, when it isn't empty. The meta has its Markdown\n * escapes taken off, and is read as SPEC §3.3.1 reads an info string, as\n * `ascribe_core::info_string` does: words parted by spaces and tabs, a pair's\n * value a token or a quoted string in which `\\\"` and `\\\\` escape, and a pair\n * followed by a space, a tab, or the end. Any other word isn't a pair.\n */\nfunction metaValue(meta: string, key: string): string | undefined {\n  let i = 0;\n  while (i < meta.length) {\n    if (meta[i] === \" \" || meta[i] === \"\\t\") {\n      i += 1;\n      continue;\n    }\n    const pair = /^([a-z][a-z0-9-]*)=/.exec(meta.slice(i));\n    let end = wordEnd(meta, i);\n    let value: string | undefined;\n    if (pair !== null) {\n      let j = i + pair[0].length;\n      if (meta[j] === '\"') {\n        let text = \"\";\n        j += 1;\n        while (j < meta.length && meta[j] !== '\"') {\n          if (meta[j] === \"\\\\\" && (meta[j + 1] === '\"' || meta[j + 1] === \"\\\\\")) j += 1;\n          text += meta[j];\n          j += 1;\n        }\n        if (j < meta.length && (j + 1 === meta.length || isSpace(meta[j + 1]))) {\n          value = text;\n          end = j + 1;\n        }\n      } else if (j < end && !meta.slice(j, end).includes('\"')) {\n        value = meta.slice(j, end);\n      }\n    }\n    if (value !== undefined && pair?.[1] === key) return value || undefined;\n    i = end;\n  }\n  return undefined;\n}\n\nfunction isSpace(c: string | undefined): boolean {\n  return c === \" \" || c === \"\\t\";\n}\n\nfunction wordEnd(text: string, from: number): number {\n  let i = from;\n  while (i < text.length && !isSpace(text[i])) i += 1;\n  return i;\n}\n\n/** The `title=\"…\"` in a code block's meta, if it has one. */\nexport function codeTitle(meta: string): string | undefined {\n  return metaValue(meta, \"title\");\n}\n\n/** The `tested=\"…\"` in a code block's meta, if it has one. */\nexport function codeTested(meta: string): string | undefined {\n  return metaValue(meta, \"tested\");\n}\n\n/**\n * The block, in a figure whose caption holds its title and its tested line;\n * `undefined` when it has neither.\n */\nexport function captioned(meta: string, block: ElementContent): Element | undefined {\n  const title = codeTitle(meta);\n  const tested = codeTested(meta);\n  if (title === undefined && tested === undefined) return undefined;\n  const caption: ElementContent[] = [];\n  if (title !== undefined) caption.push({ type: \"text\", value: title });\n  if (tested !== undefined) {\n    caption.push({\n      type: \"element\",\n      tagName: \"div\",\n      properties: { className: [CLASS_CODE_TESTED] },\n      children: [{ type: \"text\", value: tested }],\n    });\n  }\n  return {\n    type: \"element\",\n    tagName: \"figure\",\n    properties: { className: [\"code-title\"] },\n    children: [\n      { type: \"element\", tagName: \"figcaption\", properties: {}, children: caption },\n      block,\n    ],\n  };\n}\n\nexport const codeTitles: ShikiTransformer = {\n  name: \"@ascribed/astro:code-titles\",\n  root(root) {\n    const meta = (this.options.meta as { __raw?: string } | undefined)?.__raw ?? \"\";\n    const pre = root.children.find((node) => node.type === \"element\");\n    // A site's own transformer may have put it in a figure already.\n    if (pre === undefined || pre.tagName === \"figure\") return;\n    const figure = captioned(meta, pre);\n    if (figure !== undefined) root.children = [figure];\n  },\n};\n"]}

package/dist/help-file.d.ts

@@ -0,0 +1,20 @@
+/** A permalink's section, as `_ascribe/help.json` has it. */
+interface HelpEntry {
+    title: string;
+    summary?: string;
+    text: string;
+    address?: string;
+    source: string;
+}
+/** `_ascribe/help.json`. */
+export interface HelpFile {
+    version: number;
+    /** The build's name, as `ascribe.toml` declares it. */
+    build: string;
+    /** For a line of a versioned build, the line. */
+    line?: string;
+    help: Record<string, HelpEntry>;
+}
+/** The file in a build's site output, or `undefined` when there isn't one. */
+export declare function readHelp(siteRoot: string): HelpFile | undefined;
+export {};

package/dist/help-file.js

@@ -0,0 +1,24 @@
+// A build's `_ascribe/help.json` (output-layout contract §1.7): each
+// permalink's section. `help.ts` serves its entries at their own addresses,
+// and `permalinks.ts` links each forwarding page to them.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/** The file's format version this reads. */
+const VERSION = 1;
+/** The file in a build's site output, or `undefined` when there isn't one. */
+export function readHelp(siteRoot) {
+    const file = path.join(siteRoot, "_ascribe", "help.json");
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const help = JSON.parse(text);
+    if (help.version !== VERSION) {
+        throw new Error(`@ascribed/astro: ${file} is version ${String(help.version)} of the help file, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`);
+    }
+    return help;
+}
+//# sourceMappingURL=help-file.js.map

package/dist/help-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-file.js","sourceRoot":"","sources":["../src/help-file.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,4EAA4E;AAC5E,0DAA0D;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,4CAA4C;AAC5C,MAAM,OAAO,GAAG,CAAC,CAAC;AAqBlB,8EAA8E;AAC9E,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IAC1D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,eAAe,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,wEAAwE,OAAO,sDAAsD,CACjM,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// A build's `_ascribe/help.json` (output-layout contract §1.7): each\n// permalink's section. `help.ts` serves its entries at their own addresses,\n// and `permalinks.ts` links each forwarding page to them.\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** The file's format version this reads. */\nconst VERSION = 1;\n\n/** A permalink's section, as `_ascribe/help.json` has it. */\ninterface HelpEntry {\n  title: string;\n  summary?: string;\n  text: string;\n  address?: string;\n  source: string;\n}\n\n/** `_ascribe/help.json`. */\nexport interface HelpFile {\n  version: number;\n  /** The build's name, as `ascribe.toml` declares it. */\n  build: string;\n  /** For a line of a versioned build, the line. */\n  line?: string;\n  help: Record<string, HelpEntry>;\n}\n\n/** The file in a build's site output, or `undefined` when there isn't one. */\nexport function readHelp(siteRoot: string): HelpFile | undefined {\n  const file = path.join(siteRoot, \"_ascribe\", \"help.json\");\n  let text: string;\n  try {\n    text = readFileSync(file, \"utf8\");\n  } catch {\n    return undefined;\n  }\n  const help = JSON.parse(text) as HelpFile;\n  if (help.version !== VERSION) {\n    throw new Error(\n      `@ascribed/astro: ${file} is version ${String(help.version)} of the help file, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`,\n    );\n  }\n  return help;\n}\n"]}

package/dist/help-route.d.ts

@@ -1,10 +1,9 @@
 import type { APIRoute } from "astro";
+import { type HelpAnswer } from "./help.js";
 export declare const getStaticPaths: ({ routePattern }: import("astro").GetStaticPathsOptions) => {
     params: {
         id: string;
     };
-    props: {
-        body: string;
-    };
+    props: HelpAnswer;
 }[];
 export declare const GET: APIRoute;

package/dist/help-route.js

@@ -1,10 +1,16 @@
 import { base, permalinks } from "virtual:ascribe/site";
 import { helpPaths } from "./help.js";
 export const getStaticPaths = (({ routePattern }) => helpPaths(permalinks.map((source) => source.siteRoot), base, routePattern));
-export const GET = ({ props }) => new Response(props.body, {
-    headers: {
-        "Content-Type": "application/json; charset=utf-8",
-        "Access-Control-Allow-Origin": "*",
-    },
-});
+export const GET = ({ props }) => {
+    const { body, type, alternate } = props;
+    return new Response(body, {
+        headers: {
+            "Content-Type": `${type}; charset=utf-8`,
+            "Access-Control-Allow-Origin": "*",
+            ...(alternate === undefined
+                ? {}
+                : { Link: `<${alternate}>; rel="alternate"; type="text/markdown"` }),
+        },
+    });
+};
 //# sourceMappingURL=help-route.js.map

package/dist/help-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-route.js","sourceRoot":"","sources":["../src/help-route.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAClD,SAAS,CACP,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAC3C,IAAI,EACJ,YAAY,CACb,CAA0B,CAAC;AAE9B,MAAM,CAAC,MAAM,GAAG,GAAa,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CACzC,IAAI,QAAQ,CAAE,KAA0B,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE;QACP,cAAc,EAAE,iCAAiC;QACjD,6BAA6B,EAAE,GAAG;KACnC;CACF,CAAC,CAAC","sourcesContent":["// A help entry's own address: one entry of a line's `_ascribe/help.json`, as\n// JSON (`help.ts`). The integration adds this route once for each folder of\n// entries, `<path>[id].json` for the current line and `<line>/go/[id].json`\n// under the base path for each older one; which folder this is comes from\n// the route's pattern. Any origin may read it, as the build's headers say\n// for a host.\nimport type { APIRoute, GetStaticPaths } from \"astro\";\nimport { base, permalinks } from \"virtual:ascribe/site\";\nimport { helpPaths } from \"./help.js\";\n\nexport const getStaticPaths = (({ routePattern }) =>\n  helpPaths(\n    permalinks.map((source) => source.siteRoot),\n    base,\n    routePattern,\n  )) satisfies GetStaticPaths;\n\nexport const GET: APIRoute = ({ props }) =>\n  new Response((props as { body: string }).body, {\n    headers: {\n      \"Content-Type\": \"application/json; charset=utf-8\",\n      \"Access-Control-Allow-Origin\": \"*\",\n    },\n  });\n"]}
+{"version":3,"file":"help-route.js","sourceRoot":"","sources":["../src/help-route.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAmB,MAAM,WAAW,CAAC;AAEvD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAClD,SAAS,CACP,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAC3C,IAAI,EACJ,YAAY,CACb,CAA0B,CAAC;AAE9B,MAAM,CAAC,MAAM,GAAG,GAAa,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IACzC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,KAAmB,CAAC;IACtD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,OAAO,EAAE;YACP,cAAc,EAAE,GAAG,IAAI,iBAAiB;YACxC,6BAA6B,EAAE,GAAG;YAClC,GAAG,CAAC,SAAS,KAAK,SAAS;gBACzB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,0CAA0C,EAAE,CAAC;SACvE;KACF,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["// A help entry's own addresses: one entry of a line's `_ascribe/help.json`, as\n// JSON, and its section as Markdown (`help.ts`). The integration adds this\n// route once for each folder of entries and each format, `<path>[id].json`\n// and `<path>[id].md` for the current line and `<line>/go/[id].json` and\n// `<line>/go/[id].md` under the base path for each older one; which folder\n// and format this is comes from the route's pattern. Any origin may read\n// it, and the JSON names the Markdown as its alternate, as the build's\n// headers say for a host.\nimport type { APIRoute, GetStaticPaths } from \"astro\";\nimport { base, permalinks } from \"virtual:ascribe/site\";\nimport { helpPaths, type HelpAnswer } from \"./help.js\";\n\nexport const getStaticPaths = (({ routePattern }) =>\n  helpPaths(\n    permalinks.map((source) => source.siteRoot),\n    base,\n    routePattern,\n  )) satisfies GetStaticPaths;\n\nexport const GET: APIRoute = ({ props }) => {\n  const { body, type, alternate } = props as HelpAnswer;\n  return new Response(body, {\n    headers: {\n      \"Content-Type\": `${type}; charset=utf-8`,\n      \"Access-Control-Allow-Origin\": \"*\",\n      ...(alternate === undefined\n        ? {}\n        : { Link: `<${alternate}>; rel=\"alternate\"; type=\"text/markdown\"` }),\n    },\n  });\n};\n"]}

package/dist/help.d.ts

@@ -1,22 +1,4 @@
-/** A permalink's section, as `_ascribe/help.json` has it. */
-interface HelpEntry {
-    title: string;
-    summary?: string;
-    text: string;
-    address?: string;
-    source: string;
-}
-/** `_ascribe/help.json`. */
-export interface HelpFile {
-    version: number;
-    /** The build's name, as `ascribe.toml` declares it. */
-    build: string;
-    /** For a line of a versioned build, the line. */
-    line?: string;
-    help: Record<string, HelpEntry>;
-}
-/** The file in a build's site output, or `undefined` when there isn't one. */
-export declare function readHelp(siteRoot: string): HelpFile | undefined;
+import { type HelpFile } from "./help-file.js";
 /**
  * What each entry's address answers, by the address from the host's root:
  * the file it's in with that entry alone, its `version`, `build`, and
@@ -25,21 +7,32 @@ export declare function readHelp(siteRoot: string): HelpFile | undefined;
  */
 export declare function helpAddresses(siteRoots: readonly string[]): Map<string, HelpFile>;
 /**
- * The route patterns the entries need, one for each folder that has any:
- * the current line's, then each older line's. Throws when a folder isn't
- * under `base`, since an Astro site serves nothing outside it.
+ * The route patterns the entries need, for each folder that has any, its
+ * JSON's and its Markdown's: the current line's, then each older line's.
+ * Throws when a folder isn't under `base`, since an Astro site serves
+ * nothing outside it.
  */
 export declare function helpPatterns(siteRoots: readonly string[], base: string): string[];
+/**
+ * An entry's section as Markdown: its title as a heading, then its `text`,
+ * the section as the plain output writes it.
+ */
+export declare function helpMarkdown(help: HelpFile): string;
+/** What an entry's address answers: its body, and the body's media type. A record, so Astro takes it as props. */
+export interface HelpAnswer extends Record<string, unknown> {
+    body: string;
+    type: string;
+    /** For the JSON, where the same entry is as Markdown, its alternate. */
+    alternate?: string;
+}
 /**
  * `getStaticPaths` for the route at `routePattern`, one of `helpPatterns`:
- * one answer for each entry whose address it matches, the entry as JSON.
+ * one answer for each entry whose address it matches, the entry as JSON, or
+ * its section as Markdown.
  */
 export declare function helpPaths(siteRoots: readonly string[], base: string, routePattern: string): {
     params: {
         id: string;
     };
-    props: {
-        body: string;
-    };
+    props: HelpAnswer;
 }[];
-export {};

package/dist/help.js

@@ -1,33 +1,18 @@
-// Each permalink's help at an address of its own, for a product to fetch its
+// Each permalink's help at addresses of its own, for a product to fetch its
 // line's: one entry of a build's `_ascribe/help.json` (output-layout contract
-// §1.7), as JSON. The current line's entries are beside its permalinks'
-// addresses, at `<path><name>.json`; an older line's are at `go/<name>.json`
-// under the line's own base path, `/docs/3.4/go/connect.json`, since the
-// permalinks' addresses are the current line's. The integration adds a route
-// (`help-route.ts`) for each of those folders, in `astro build` and `astro dev`.
-import { readFileSync } from "node:fs";
+// §1.7), as JSON, and its section as Markdown, for an agent to read the
+// section a permalink names in one fetch. The current line's entries are
+// beside its permalinks' addresses, at `<path><name>.json` and
+// `<path><name>.md`; an older line's are at `go/<name>.json` and
+// `go/<name>.md` under the line's own base path, `/docs/3.4/go/connect.json`,
+// since the permalinks' addresses are the current line's. The integration
+// adds a route (`help-route.ts`) for each of those folders and each format,
+// in `astro build` and `astro dev`.
 import path from "node:path";
+import { readHelp } from "./help-file.js";
 import { permalinkPattern, readPermalinks } from "./permalinks.js";
 import { normalizeBase } from "./project.js";
 import { olderLines } from "./versions.js";
-/** The file's format version this reads. */
-const VERSION = 1;
-/** The file in a build's site output, or `undefined` when there isn't one. */
-export function readHelp(siteRoot) {
-    const file = path.join(siteRoot, "_ascribe", "help.json");
-    let text;
-    try {
-        text = readFileSync(file, "utf8");
-    }
-    catch {
-        return undefined;
-    }
-    const help = JSON.parse(text);
-    if (help.version !== VERSION) {
-        throw new Error(`@ascribed/astro: ${file} is version ${String(help.version)} of the help file, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`);
-    }
-    return help;
-}
 /**
  * Each line's file, with the folder its entries are served under: the
  * current line's at the permalinks' path, each older line's at `go/` under
@@ -70,32 +55,60 @@ export function helpAddresses(siteRoots) {
     }
     return addresses;
 }
-/** The route pattern for a folder's entries, as Astro takes it: under `base`, which Astro adds. */
-function helpPattern(folder, base) {
-    return `${permalinkPattern(folder, base)}.json`;
+/** The formats an entry is served in, by the extension its address ends with. */
+const FORMATS = [".json", ".md"];
+/** The route pattern for a folder's entries in a format, as Astro takes it: under `base`, which Astro adds. */
+function helpPattern(folder, base, extension) {
+    return `${permalinkPattern(folder, base)}${extension}`;
 }
 /**
- * The route patterns the entries need, one for each folder that has any:
- * the current line's, then each older line's. Throws when a folder isn't
- * under `base`, since an Astro site serves nothing outside it.
+ * The route patterns the entries need, for each folder that has any, its
+ * JSON's and its Markdown's: the current line's, then each older line's.
+ * Throws when a folder isn't under `base`, since an Astro site serves
+ * nothing outside it.
  */
 export function helpPatterns(siteRoots, base) {
     const patterns = helpFolders(siteRoots)
         .filter(({ help }) => Object.keys(help.help).length > 0)
-        .map(({ folder }) => helpPattern(folder, base));
+        .flatMap(({ folder }) => FORMATS.map((extension) => helpPattern(folder, base, extension)));
     return [...new Set(patterns)];
 }
+/**
+ * An entry's section as Markdown: its title as a heading, then its `text`,
+ * the section as the plain output writes it.
+ */
+export function helpMarkdown(help) {
+    const [entry] = Object.values(help.help);
+    if (entry === undefined)
+        return "";
+    const text = entry.text.trimEnd();
+    return text === "" ? `# ${entry.title}\n` : `# ${entry.title}\n\n${text}\n`;
+}
 /**
  * `getStaticPaths` for the route at `routePattern`, one of `helpPatterns`:
- * one answer for each entry whose address it matches, the entry as JSON.
+ * one answer for each entry whose address it matches, the entry as JSON, or
+ * its section as Markdown.
  */
 export function helpPaths(siteRoots, base, routePattern) {
     return [...helpAddresses(siteRoots)].flatMap(([address, help]) => {
         const name = path.posix.basename(address, ".json");
         const folder = address.slice(0, address.length - `${name}.json`.length);
-        return helpPattern(folder, base) === routePattern
-            ? [{ params: { id: name }, props: { body: `${JSON.stringify(help, null, 2)}\n` } }]
-            : [];
+        if (helpPattern(folder, base, ".json") === routePattern) {
+            return [
+                {
+                    params: { id: name },
+                    props: {
+                        body: `${JSON.stringify(help, null, 2)}\n`,
+                        type: "application/json",
+                        alternate: `${folder}${name}.md`,
+                    },
+                },
+            ];
+        }
+        if (helpPattern(folder, base, ".md") === routePattern) {
+            return [{ params: { id: name }, props: { body: helpMarkdown(help), type: "text/markdown" } }];
+        }
+        return [];
     });
 }
 //# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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","sourcesContent":["// Each permalink's help at an address of its own, for a product to fetch its\n// line's: one entry of a build's `_ascribe/help.json` (output-layout contract\n// §1.7), as JSON. The current line's entries are beside its permalinks'\n// addresses, at `<path><name>.json`; an older line's are at `go/<name>.json`\n// under the line's own base path, `/docs/3.4/go/connect.json`, since the\n// permalinks' addresses are the current line's. The integration adds a route\n// (`help-route.ts`) for each of those folders, in `astro build` and `astro dev`.\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { permalinkPattern, readPermalinks } from \"./permalinks.js\";\nimport { normalizeBase } from \"./project.js\";\nimport { olderLines } from \"./versions.js\";\n\n/** The file's format version this reads. */\nconst VERSION = 1;\n\n/** A permalink's section, as `_ascribe/help.json` has it. */\ninterface HelpEntry {\n  title: string;\n  summary?: string;\n  text: string;\n  address?: string;\n  source: string;\n}\n\n/** `_ascribe/help.json`. */\nexport interface HelpFile {\n  version: number;\n  /** The build's name, as `ascribe.toml` declares it. */\n  build: string;\n  /** For a line of a versioned build, the line. */\n  line?: string;\n  help: Record<string, HelpEntry>;\n}\n\n/** The file in a build's site output, or `undefined` when there isn't one. */\nexport function readHelp(siteRoot: string): HelpFile | undefined {\n  const file = path.join(siteRoot, \"_ascribe\", \"help.json\");\n  let text: string;\n  try {\n    text = readFileSync(file, \"utf8\");\n  } catch {\n    return undefined;\n  }\n  const help = JSON.parse(text) as HelpFile;\n  if (help.version !== VERSION) {\n    throw new Error(\n      `@ascribed/astro: ${file} is version ${String(help.version)} of the help file, and this version of the integration reads version ${VERSION}. Update @ascribed/astro and @ascribed/cli together.`,\n    );\n  }\n  return help;\n}\n\n/** A folder of entries' addresses, from the host's root, and the file they're served from. */\ninterface HelpFolder {\n  folder: string;\n  help: HelpFile;\n}\n\n/**\n * Each line's file, with the folder its entries are served under: the\n * current line's at the permalinks' path, each older line's at `go/` under\n * its base path. A site output with no file, or no permalinks list, has none.\n */\nfunction helpFolders(siteRoots: readonly string[]): HelpFolder[] {\n  return siteRoots.flatMap((siteRoot) => {\n    const list = readPermalinks(siteRoot);\n    const help = readHelp(siteRoot);\n    const current =\n      list === undefined || help === undefined ? [] : [{ folder: normalizeBase(list.path), help }];\n    const older = olderLines(siteRoot).flatMap((line) => {\n      const lineHelp = readHelp(line.siteRoot);\n      return lineHelp === undefined\n        ? []\n        : [{ folder: `${normalizeBase(line.base)}go/`, help: lineHelp }];\n    });\n    return [...current, ...older];\n  });\n}\n\n/**\n * What each entry's address answers, by the address from the host's root:\n * the file it's in with that entry alone, its `version`, `build`, and\n * `line` as the file has them, so a product reads a fetched entry and its\n * bundled copy alike. An address two files give keeps the first's.\n */\nexport function helpAddresses(siteRoots: readonly string[]): Map<string, HelpFile> {\n  const addresses = new Map<string, HelpFile>();\n  for (const { folder, help } of helpFolders(siteRoots)) {\n    for (const [name, entry] of Object.entries(help.help)) {\n      const address = `${folder}${name}.json`;\n      if (addresses.has(address)) continue;\n      addresses.set(address, {\n        version: help.version,\n        build: help.build,\n        ...(help.line === undefined ? {} : { line: help.line }),\n        help: { [name]: entry },\n      });\n    }\n  }\n  return addresses;\n}\n\n/** The route pattern for a folder's entries, as Astro takes it: under `base`, which Astro adds. */\nfunction helpPattern(folder: string, base: string): string {\n  return `${permalinkPattern(folder, base)}.json`;\n}\n\n/**\n * The route patterns the entries need, one for each folder that has any:\n * the current line's, then each older line's. Throws when a folder isn't\n * under `base`, since an Astro site serves nothing outside it.\n */\nexport function helpPatterns(siteRoots: readonly string[], base: string): string[] {\n  const patterns = helpFolders(siteRoots)\n    .filter(({ help }) => Object.keys(help.help).length > 0)\n    .map(({ folder }) => helpPattern(folder, base));\n  return [...new Set(patterns)];\n}\n\n/**\n * `getStaticPaths` for the route at `routePattern`, one of `helpPatterns`:\n * one answer for each entry whose address it matches, the entry as JSON.\n */\nexport function helpPaths(\n  siteRoots: readonly string[],\n  base: string,\n  routePattern: string,\n): { params: { id: string }; props: { body: string } }[] {\n  return [...helpAddresses(siteRoots)].flatMap(([address, help]) => {\n    const name = path.posix.basename(address, \".json\");\n    const folder = address.slice(0, address.length - `${name}.json`.length);\n    return helpPattern(folder, base) === routePattern\n      ? [{ params: { id: name }, props: { body: `${JSON.stringify(help, null, 2)}\\n` } }]\n      : [];\n  });\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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","sourcesContent":["// Each permalink's help at addresses of its own, for a product to fetch its\n// line's: one entry of a build's `_ascribe/help.json` (output-layout contract\n// §1.7), as JSON, and its section as Markdown, for an agent to read the\n// section a permalink names in one fetch. The current line's entries are\n// beside its permalinks' addresses, at `<path><name>.json` and\n// `<path><name>.md`; an older line's are at `go/<name>.json` and\n// `go/<name>.md` under the line's own base path, `/docs/3.4/go/connect.json`,\n// since the permalinks' addresses are the current line's. The integration\n// adds a route (`help-route.ts`) for each of those folders and each format,\n// in `astro build` and `astro dev`.\nimport path from \"node:path\";\nimport { readHelp, type HelpFile } from \"./help-file.js\";\nimport { permalinkPattern, readPermalinks } from \"./permalinks.js\";\nimport { normalizeBase } from \"./project.js\";\nimport { olderLines } from \"./versions.js\";\n\n/** A folder of entries' addresses, from the host's root, and the file they're served from. */\ninterface HelpFolder {\n  folder: string;\n  help: HelpFile;\n}\n\n/**\n * Each line's file, with the folder its entries are served under: the\n * current line's at the permalinks' path, each older line's at `go/` under\n * its base path. A site output with no file, or no permalinks list, has none.\n */\nfunction helpFolders(siteRoots: readonly string[]): HelpFolder[] {\n  return siteRoots.flatMap((siteRoot) => {\n    const list = readPermalinks(siteRoot);\n    const help = readHelp(siteRoot);\n    const current =\n      list === undefined || help === undefined ? [] : [{ folder: normalizeBase(list.path), help }];\n    const older = olderLines(siteRoot).flatMap((line) => {\n      const lineHelp = readHelp(line.siteRoot);\n      return lineHelp === undefined\n        ? []\n        : [{ folder: `${normalizeBase(line.base)}go/`, help: lineHelp }];\n    });\n    return [...current, ...older];\n  });\n}\n\n/**\n * What each entry's address answers, by the address from the host's root:\n * the file it's in with that entry alone, its `version`, `build`, and\n * `line` as the file has them, so a product reads a fetched entry and its\n * bundled copy alike. An address two files give keeps the first's.\n */\nexport function helpAddresses(siteRoots: readonly string[]): Map<string, HelpFile> {\n  const addresses = new Map<string, HelpFile>();\n  for (const { folder, help } of helpFolders(siteRoots)) {\n    for (const [name, entry] of Object.entries(help.help)) {\n      const address = `${folder}${name}.json`;\n      if (addresses.has(address)) continue;\n      addresses.set(address, {\n        version: help.version,\n        build: help.build,\n        ...(help.line === undefined ? {} : { line: help.line }),\n        help: { [name]: entry },\n      });\n    }\n  }\n  return addresses;\n}\n\n/** The formats an entry is served in, by the extension its address ends with. */\nconst FORMATS = [\".json\", \".md\"] as const;\n\n/** The route pattern for a folder's entries in a format, as Astro takes it: under `base`, which Astro adds. */\nfunction helpPattern(folder: string, base: string, extension: string): string {\n  return `${permalinkPattern(folder, base)}${extension}`;\n}\n\n/**\n * The route patterns the entries need, for each folder that has any, its\n * JSON's and its Markdown's: the current line's, then each older line's.\n * Throws when a folder isn't under `base`, since an Astro site serves\n * nothing outside it.\n */\nexport function helpPatterns(siteRoots: readonly string[], base: string): string[] {\n  const patterns = helpFolders(siteRoots)\n    .filter(({ help }) => Object.keys(help.help).length > 0)\n    .flatMap(({ folder }) => FORMATS.map((extension) => helpPattern(folder, base, extension)));\n  return [...new Set(patterns)];\n}\n\n/**\n * An entry's section as Markdown: its title as a heading, then its `text`,\n * the section as the plain output writes it.\n */\nexport function helpMarkdown(help: HelpFile): string {\n  const [entry] = Object.values(help.help);\n  if (entry === undefined) return \"\";\n  const text = entry.text.trimEnd();\n  return text === \"\" ? `# ${entry.title}\\n` : `# ${entry.title}\\n\\n${text}\\n`;\n}\n\n/** What an entry's address answers: its body, and the body's media type. A record, so Astro takes it as props. */\nexport interface HelpAnswer extends Record<string, unknown> {\n  body: string;\n  type: string;\n  /** For the JSON, where the same entry is as Markdown, its alternate. */\n  alternate?: string;\n}\n\n/**\n * `getStaticPaths` for the route at `routePattern`, one of `helpPatterns`:\n * one answer for each entry whose address it matches, the entry as JSON, or\n * its section as Markdown.\n */\nexport function helpPaths(\n  siteRoots: readonly string[],\n  base: string,\n  routePattern: string,\n): { params: { id: string }; props: HelpAnswer }[] {\n  return [...helpAddresses(siteRoots)].flatMap(([address, help]) => {\n    const name = path.posix.basename(address, \".json\");\n    const folder = address.slice(0, address.length - `${name}.json`.length);\n    if (helpPattern(folder, base, \".json\") === routePattern) {\n      return [\n        {\n          params: { id: name },\n          props: {\n            body: `${JSON.stringify(help, null, 2)}\\n`,\n            type: \"application/json\",\n            alternate: `${folder}${name}.md`,\n          },\n        },\n      ];\n    }\n    if (helpPattern(folder, base, \".md\") === routePattern) {\n      return [{ params: { id: name }, props: { body: helpMarkdown(help), type: \"text/markdown\" } }];\n    }\n    return [];\n  });\n}\n"]}

package/dist/index.js

@@ -45,6 +45,7 @@ import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findBinary } from "./binary.js";
+import { codeLanguages } from "./code-languages.js";
 import { codeTitles } from "./code-titles.js";
 import { SeenFiles, watchDev } from "./dev.js";
 import { agentsMiddleware, copyAgentFiles, copyPublishedFiles, filesMiddleware, folderUnder, inOrder, } from "./files.js";
@@ -326,9 +327,9 @@ export default function ascribe(options) {
                             prerender: true,
                         });
                     }
-                    // Each permalink's help, at `<name>.json` beside its address, and each older line's
-                    // under the line's base path. One route for each folder: the current line's, then each
-                    // older line's.
+                    // Each permalink's help, at `<name>.json` and `<name>.md` beside its address, and each
+                    // older line's under the line's base path. One route for each folder and format: the
+                    // current line's, then each older line's.
                     for (const pattern of helpPatterns(entries.map((entry) => entry.siteRoot), astro.base)) {
                         injectRoute({
                             pattern,
@@ -342,9 +343,11 @@ export default function ascribe(options) {
                 updateConfig({
                     ...supplied,
                     ...(format.supplied === undefined ? {} : { build: { format: format.supplied } }),
-                    ...(options.codeTitles === false
-                        ? {}
-                        : { markdown: { shikiConfig: { transformers: [codeTitles] } } }),
+                    markdown: {
+                        shikiConfig: {
+                            transformers: options.codeTitles === false ? [codeLanguages] : [codeTitles, codeLanguages],
+                        },
+                    },
                     vite: {
                         // `Elements.astro` is Astro source, so Vite must compile it, not load it as a Node module.
                         ssr: { noExternal: ["@ascribed/astro"] },