vowel 0.7.8 → 0.8.1

package/plugins/html/markdownGrammar.js

@@ -0,0 +1,152 @@
+/**
+ * Prism's markdown grammar, made to read what Vowel reads: GitHub
+ * Flavored Markdown, then Vowel's own syntax on top (per Sam, Nov 6:
+ * Vowel is a GFM superset, so its code blocks highlight as GFM).
+ *
+ * Prism's grammar is close. These change what it gets wrong, measured
+ * against micromark, which Vowel parses pages with:
+ *
+ * - frontmatter only on the first line (Prism allowed blank lines
+ *   before it);
+ * - fences of `~~~` as well as ```, and longer fences (a `~~~` fence was
+ *   strikethrough, and a ```` fence ended at the first ``` inside it);
+ * - table delimiter cells of one dash (Prism wanted three);
+ * - task list items, footnotes and autolinks, which it didn't know.
+ *
+ * And these add Vowel's syntax, with the patterns `readRules.js` reads
+ * it with: alerts, wikilinks, hashtags, `:shortcodes:`, `==highlights==`
+ * and listing lines (`/blog/*`).
+ *
+ * Prism grammars are objects that are changed in place: `insertBefore`
+ * is how a rule is added, and the order of rules is the order they are
+ * tried in. A token that is cut out of a line hides it from the rules
+ * after it: that is why a task item takes its list marker with it.
+ */
+
+/**
+ * Prism's table patterns with one dash or more per delimiter cell.
+ * @param {RegExp} pattern
+ */
+const oneDash = (pattern) => new RegExp(pattern.source.replaceAll("-{3,}", "-+"), pattern.flags)
+
+/**
+ * Extends the markdown grammar of this refractor, once.
+ * @param {import("refractor/core").Refractor} refractor - with markdown registered
+ */
+export function extendMarkdown(refractor) {
+  const languages = refractor.languages
+  const markdown = languages.markdown
+
+  markdown["front-matter-block"].pattern = /^---(?!.)[\s\S]*?[\r\n]---(?!.)/
+  markdown["front-matter-block"].lookbehind = false
+
+  // Three or more backticks or tildes, closed by the same character at
+  // least as many times. Prism's after-tokenize hook reads the language
+  // from the parts and highlights the block in it, and it finds them by
+  // position: the language second, the block fourth. So the language is
+  // the first word only, never a quoted title (codeFence.js), and the
+  // rest of the line, a title and its newline, is one token in third
+  // place, where the newline would be: fence, language, meta, block,
+  // newline, fence.
+  markdown.code[1] = {
+    pattern: /^(([`~])\2{2,})[^\r\n]*(?:\r\n?|\n)(?:[\s\S]*?(?:\r\n?|\n))??\1\2*[ \t]*$/m,
+    greedy: true,
+    inside: {
+      "code-block": {
+        pattern: /^((?:`{3,}|~{3,})[^\r\n]*(?:\r\n?|\n))[\s\S]+(?=(?:\r\n?|\n)(?:`{3,}|~{3,})[ \t]*$)/,
+        lookbehind: true
+      },
+      "code-language": {
+        pattern: /^(`{3,}|~{3,})[^\s`~"'][^\s]*/,
+        lookbehind: true
+      },
+      punctuation: /`{3,}|~{3,}/,
+      "code-meta": {
+        pattern: /^[ \t]*[^\s][^\r\n]*(?:\r\n?|\n)$/,
+        inside: { string: /"[^"]*"|'[^']*'/ }
+      }
+    }
+  }
+
+  const table = markdown.table
+  const rows = table.inside["table-data-rows"]
+  const line = table.inside["table-line"]
+  table.pattern = oneDash(table.pattern)
+  rows.pattern = oneDash(rows.pattern)
+  line.pattern = oneDash(line.pattern)
+  line.inside.punctuation = oneDash(line.inside.punctuation)
+
+  languages.insertBefore("markdown", "blockquote", {
+    // `> [!NOTE]`, any word, at the start of a quote.
+    alert: {
+      pattern: /(^>[ \t]*)\[![A-Za-z]+\]/m,
+      lookbehind: true,
+      alias: "important"
+    }
+  })
+
+  languages.insertBefore("markdown", "list", {
+    // `- [x]` and `1. [ ]`.
+    task: {
+      pattern: /^[ \t]*(?:[*+-]|\d+[.)])[ \t]+\[[ xX]\](?=[ \t])/m,
+      inside: {
+        list: { pattern: /^[ \t]*(?:[*+-]|\d+[.)])/, alias: "punctuation" },
+        checkbox: { pattern: /\[[ xX]\]/, alias: "keyword" }
+      }
+    },
+    // A paragraph that is only a path: a listing (`/blog/*`, `./drafts/**`)
+    // or a reference to a page (`/blog/post`).
+    directive: {
+      pattern: /(^|\n[ \t]*\n)(?:\/|\.\.?\/)\S*(?=[ \t]*(?:\n[ \t]*\n|\n?$))/,
+      lookbehind: true,
+      alias: "function"
+    }
+  })
+
+  languages.insertBefore("markdown", "url-reference", {
+    // `[^1]: The source.`, which Prism read as a link definition with
+    // the first word as its url.
+    "footnote-definition": {
+      pattern: /^[ \t]*\[\^[^\]\s]+\]:/m,
+      alias: "url"
+    }
+  })
+
+  languages.insertBefore("markdown", "url", {
+    // `[[Name]]`, `[[Name#Section]]`, `[[Name|words]]` and `![[Name]]`.
+    wikilink: {
+      pattern: /!?\[\[[^\]|#\r\n]+(?:#[^\]|\r\n]+)?(?:\|[^\]\r\n]+)?\]\]/,
+      greedy: true,
+      alias: "url",
+      inside: { punctuation: /^!?\[\[|\]\]$|[|#]/ }
+    },
+    // `[^1]`
+    footnote: {
+      pattern: /\[\^[^\]\s]+\]/,
+      alias: "url"
+    },
+    // `<https://vowel.cc>`, and a bare `https://vowel.cc` without the
+    // punctuation that ends a sentence.
+    autolink: {
+      pattern: /<(?:https?|mailto):[^\s>]+>|\bhttps?:\/\/[^\s<]*[^\s<.,:;"')\]]/,
+      alias: "url"
+    },
+    // `#tag` after the start of a line or a space: never a heading's
+    // `# `, a salt's `##` or the `#` in `a#b`.
+    hashtag: {
+      pattern: /(^|[ \t])#[\w\-/]+\b/m,
+      lookbehind: true,
+      alias: "tag"
+    },
+    // `:name:` and `:folder/name:`, an emoji or an icon.
+    shortcode: {
+      pattern: /:[a-z0-9_+-]+(?:\/[a-z0-9_+-]+)?:/,
+      alias: "symbol"
+    },
+    // `==highlighted==`
+    mark: {
+      pattern: /==(?=\S)[^=\r\n]*\S==/,
+      alias: "important"
+    }
+  })
+}

package/plugins/html/partials.js

@@ -1,6 +1,6 @@
 import path from "node:path"
 import { h } from "hastscript"
-import { isListedPage } from "../../utils.js"
+import { isListedPage, pageClasses } from "../../utils.js"
 import { isVowelStylesheet } from "../styles/theme.js"
 
 /** The one stylesheet name linked without being asked for. */
@@ -96,8 +96,26 @@ function chain(folder) {
   return ["", ...segments.map((_, i) => segments.slice(0, i + 1).join(path.sep))]
 }
 
-/** A nav entry: where it goes and what it says. */
-const item = (page) => ({ url: page.metadata.prettyURL, label: page.metadata.breadcrumb })
+/**
+ * The class a nav's `<li>` carries (per Sam, Nov 7): the page class of
+ * the page it links to, the same as that page's `<body>` and cards
+ * (`page_blog_hello-world`).
+ * @param {any} page
+ */
+const pageClass = (page) => pageClasses(page.metadata.prettyURL, page.source).at(-1)
+
+/**
+ * The class a nav's `<ul>` carries: the folder its pages are in, as
+ * their own classes name it (`folder_blog`), or null for the root's.
+ * @param {any[]} pages - one folder's
+ */
+const folderClass = (pages) => {
+  const classes = pages.length ? pageClasses(pages[0].metadata.prettyURL, pages[0].source) : []
+  return classes.length > 1 ? classes.at(-2) : null
+}
+
+/** A nav entry: where it goes, what it says, and its page's class. */
+const item = (page) => ({ url: page.metadata.prettyURL, label: page.metadata.breadcrumb, page: pageClass(page) })
 
 /**
  * The aside tree: top-level pages with no date, each with the pages of
@@ -118,16 +136,14 @@ function asideTree(pages) {
     byFolder.get(url).push(page)
   }
   // A folder with too many pages for a menu shows its own entry only (asMenu).
-  const children = (parent) => {
-    const pages = byFolder.get(parent.metadata.prettyURL) ?? []
-    return asMenu(pages).map(node)
-  }
+  const children = (parent) => asMenu(byFolder.get(parent.metadata.prettyURL) ?? [])
 
   function node(page) {
     const below = children(page)
     // The aside links the file, not the pretty url - kept as it was
     // (see the note in the commit).
-    return { url: "/" + page.path, label: page.metadata.breadcrumb, ...(below.length ? { children: below } : {}) }
+    const entry = { url: "/" + page.path, label: page.metadata.breadcrumb, page: pageClass(page) }
+    return below.length ? { ...entry, children: below.map(node), folder: folderClass(below) } : entry
   }
 
   const top = undated
@@ -241,7 +257,8 @@ function createPartialStubs(api) {
       // it, a folder with too many pages shows none of them (asMenu).
       levels: chain(folder).map(level => {
         const list = lists.get(level) ?? []
-        return (level ? asMenu(list) : list).map(item)
+        const shown = level ? asMenu(list) : list
+        return { folder: folderClass(shown), items: shown.map(item) }
       }),
       sheets: chain(folder).flatMap(level => sheets.get(level) ?? [])
     }
@@ -255,20 +272,30 @@ function expandPartial({ params }) {
   return { text: JSON.stringify(params) }
 }
 
-/** The header nav: one <ul> per level that has entries, root first. */
+/**
+ * The header nav: one <ul> per level that has entries, root first.
+ * Labelled "Local" and the aside "Global", after the settings that
+ * leave a page out of each (`local_nav_item`, `global_nav_item`), so a
+ * screen reader can tell the page's navs apart. The labels are CSS
+ * hooks too, like `nav[aria-label=Breadcrumbs]`: renaming one breaks
+ * an author's stylesheet.
+ */
 function renderNav({ levels }) {
-  return h("nav", levels
-    .filter(level => level.length)
-    .map(level => h("ul", level.map(({ url, label }) => h("li", h("a", { href: url }, label)))))
+  return h("nav", { "aria-label": "Local" }, levels
+    .filter(level => level.items.length)
+    .map(level => h("ul", classed(level.folder), level.items.map(({ url, label, page }) => h("li", classed(page), h("a", { href: url }, label)))))
   )
 }
 
+/** One class, or none. @param {string | null | undefined} name */
+const classed = (name) => name ? { className: [name] } : {}
+
 /** The aside tree. */
 function renderAside({ items }) {
-  const li = ({ url, label, children }) => children
-    ? h("li", [h("a", { href: url }, label), h("ul", children.map(li))])
-    : h("li", h("a", { href: url }, label))
-  return h("nav", h("ul", items.map(li)))
+  const li = ({ url, label, page, children, folder }) => children
+    ? h("li", classed(page), [h("a", { href: url }, label), h("ul", classed(folder), children.map(li))])
+    : h("li", classed(page), h("a", { href: url }, label))
+  return h("nav", { "aria-label": "Global" }, h("ul", items.map(li)))
 }
 
 /** "Linked from", outside section#content: it is generated, and the editor must not see it. */
@@ -294,16 +321,39 @@ function readPartial(source) {
 }
 
 /**
- * The page's copy of a nav, with the current page marked. A copy: the
- * tracked read hands back a fresh parse, but a rule that relies on that
- * would be fragile, and the walk mutates.
+ * A nav link's href as the page url it names: the aside links files
+ * (`/blog.html`, and `/index.html` for the home page), the header nav
+ * pretty urls.
+ * @param {string} href
+ */
+const linkedURL = (href) => href === "/index.html" ? "/" : href.replace(/\.html$/, "")
+
+/**
+ * The urls of the folders above a page, not the root: `/blog` and
+ * `/blog/2020` for `/blog/2020/post`. Each is its folder's index page.
+ * @param {string} url
+ */
+function ancestorURLs(url) {
+  const segments = url.split("/").filter(Boolean)
+  return segments.slice(0, -1).map((segment, index) => "/" + segments.slice(0, index + 1).join("/"))
+}
+
+/**
+ * The page's copy of a nav, with the current page marked
+ * `aria-current=page` and the folders above it `aria-current=true`
+ * (per Sam, Nov 7), the home page aside, since every page is below it.
+ * A copy: the tracked read hands back a fresh parse, but a rule that
+ * relies on that would be fragile, and the walk mutates.
  * @param {any} hast
  * @param {string} url - the page's prettyURL
  */
 function withCurrent(hast, url) {
   const copy = structuredClone(hast)
+  const ancestors = new Set(ancestorURLs(url))
   const walk = (node) => {
-    if (node.type === "element" && node.tagName === "a" && node.properties?.href === url) node.properties.ariaCurrent = "page"
+    const href = node.type === "element" && node.tagName === "a" && typeof node.properties?.href === "string" ? linkedURL(node.properties.href) : null
+    if (href === url) node.properties.ariaCurrent = "page"
+    else if (href !== null && ancestors.has(href)) node.properties.ariaCurrent = "true"
     node.children?.forEach(walk)
   }
   walk(copy)

package/plugins/html/socialLinks.js

@@ -1,6 +1,7 @@
 import { h } from "hastscript"
 import { imageSizes } from "../../utils.js"
 import { imageURL } from "./image.js"
+import { isExternalURL, externalProperties } from "./externalLinks.js"
 
 /**
  * Social links, from the `social_links` setting:
@@ -52,6 +53,7 @@ function socialLinks(settings) {
 function socialLinksNav(settings, api) {
   const links = socialLinks(settings)
   if (!links.length) return null
+  const domain = settings?.lastNonNull?.("fm_domain")
 
   return h("nav.social-links", { "aria-label": "Social links" },
     h("ul", links.map(({ label, url, icon }) => {
@@ -61,7 +63,8 @@ function socialLinksNav(settings, api) {
       // published (image.js).
       const iconURL = icon ? imageURL(String(icon), api, imageSizes[0]) : null
       const image = iconURL && h("img", { src: iconURL, alt: text, style: `--url-icon: url("${iconURL}")` })
-      return h("li", h("a", { href: url, rel: "me" }, image || text))
+      const properties = { href: url, rel: "me" }
+      return h("li", h("a", isExternalURL(url, domain) ? externalProperties(properties) : properties, image || text))
     }))
   )
 }

package/plugins/html/writeRules.js

@@ -1,13 +1,15 @@
 import path from "node:path"
 import { h } from "hastscript"
-import { common, createLowlight } from "lowlight"
 import { toText } from "hast-util-to-text"
 import GithubSlugger from "github-slugger"
 import { createVisitor, SKIP } from "../markdown/visitor.js"
 import { showPages, isPageWithoutFile, imageSizes, sourceLocation } from "../../utils.js"
 import { globClasses, alertLabel } from "./editor/directives.js"
 import createDynamicImage, { derivativeURL } from "./image.js"
+import { highlightCode } from "./highlighting.js"
 import { displayPath } from "../../secretPaths.js"
+import { isExternalURL, externalProperties } from "./externalLinks.js"
+import { HEADING_ID_PREFIX, headingAnchor, withHeadingAnchor } from "./headingIds.js"
 
 /**
  * The page's source, at the node a warning is about (utils.js). Nodes
@@ -31,7 +33,6 @@ const at = (node, target) => sourceLocation(target.source ?? target.path, node?.
  * write can link the highlight stylesheet only on pages that need it.
  */
 
-const lowlight = createLowlight(common)
 
 /** @param {any} node */
 const isElement = (node) => node?.type === "element"
@@ -149,8 +150,39 @@ const internalLink = {
       return
     }
     // A link to a png or jpeg opens its largest derivative: the
-    // original is not published (image.js).
-    node.properties.href = (derivativeURL(found, imageSizes.at(-1)) ?? urlOf(found)) + suffix
+    // original is not published (image.js). A page's anchor is a
+    // heading's (headingIds.js); a file's, like a pdf's `#page=2`, isn't.
+    const anchored = found.extension === ".html" ? withHeadingAnchor(suffix) : suffix
+    node.properties.href = (derivativeURL(found, imageSizes.at(-1)) ?? urlOf(found)) + anchored
+  }
+}
+
+/**
+ * `[x](#kerning)`, an anchor on this page: a heading's, so `#heading_kerning`
+ * (headingIds.js). In place, so the walk goes on into its text.
+ * @type {import("../markdown/visitor.js").BlockRule}
+ */
+const anchorLink = {
+  name: "anchorLink",
+  test: (node) => isElement(node) && node.tagName === "a" && typeof node.properties?.href === "string" && node.properties.href.startsWith("#"),
+  transform: (node) => {
+    node.properties.href = "#" + headingAnchor(node.properties.href.slice(1))
+  }
+}
+
+/**
+ * A link to another site opens in a new tab (externalLinks.js). Any
+ * absolute link matches; one to the site's own domain is left as it
+ * is, which a test can't tell, since only the transform has the
+ * settings. In place, so the walk goes on into its text.
+ * @type {import("../markdown/visitor.js").BlockRule}
+ */
+const externalLink = {
+  name: "externalLink",
+  test: (node) => isElement(node) && node.tagName === "a" && /^(https?:)?\/\//i.test(node.properties?.href ?? ""),
+  transform: (node, index, parent, { settings }) => {
+    if (!isExternalURL(node.properties.href, settings?.lastNonNull?.("fm_domain"))) return
+    node.properties = externalProperties(node.properties)
   }
 }
 
@@ -248,7 +280,7 @@ const wikilink = {
       return SKIP
     }
     const url = found.metadata?.prettyURL ?? `/${found.path}`
-    const anchor = section ? `#${new GithubSlugger().slug(section)}` : ""
+    const anchor = section ? `#${HEADING_ID_PREFIX}${new GithubSlugger().slug(section)}` : ""
     node.properties.href = url + anchor
     return SKIP
   }
@@ -276,9 +308,10 @@ const icon = {
 }
 
 /**
- * A fenced block with a language: what rehype-highlight did, without
- * its walk. hljs plus per-token spans on the <code>; the language class
- * is left for the stylesheet. An unregistered language is left alone.
+ * A fenced block with a language, highlighted by Prism
+ * (highlighting.js): per-token spans in the <code>, and the language
+ * class on the <pre> as well as the <code>, where Prism's themes look
+ * for it. A language Prism doesn't know is left alone.
  * @type {import("../markdown/visitor.js").BlockRule}
  */
 const highlight = {
@@ -288,14 +321,10 @@ const highlight = {
     const code = node.children[0]
     const language = (code.properties?.className ?? []).map(String).find(name => name.startsWith("language-"))?.slice("language-".length)
     if (!language) return SKIP
-    let result
-    try {
-      result = lowlight.highlight(language, toText(code, { whitespace: "pre" }))
-    } catch (error) {
-      if (/Unknown language/.test(error.message)) return SKIP
-      throw error
-    }
-    code.properties.className = ["hljs", ...code.properties.className.filter(name => name !== "hljs")]
+    const result = highlightCode(toText(code, { whitespace: "pre" }), language)
+    if (!result) return SKIP
+    const preClasses = (node.properties?.className ?? []).map(String).filter(name => !name.startsWith("language-"))
+    node.properties = { ...node.properties, className: [...preClasses, `language-${language}`] }
     if (result.children.length) code.children = result.children
     context.highlighted = true
     return SKIP
@@ -327,6 +356,7 @@ const captionedImage = {
   transform: (node) => {
     const [img, ...caption] = node.children
     node.tagName = "figure"
+    node.properties = { ...node.properties, className: [...(node.properties?.className ?? []), "image"] }
     node.children = [img, h("figcaption", caption)]
   }
 }
@@ -423,7 +453,7 @@ const directive = {
       // Lowercased: every vowel target path is (config.js's router).
       const found = api.target(path.relative("/", path.format(info)).toLowerCase())
       if (!found) return SKIP
-      return makeHeader(found.metadata, cardLink(found), api, config, found.source)
+      return asReference(makeHeader(found.metadata, cardLink(found), api, config, found.source))
     }
 
     const folder = path.relative("/", dir)
@@ -459,6 +489,19 @@ const directive = {
  */
 const cardLink = (found) => isPageWithoutFile(found) ? null : found.metadata.prettyURL
 
+/**
+ * A reference card's <article> marked `reference`, which a listing's
+ * cards aren't: `<a><article class=reference>`, or the article alone for
+ * a page with no file. The editor's ingest reads it to put `/blog/post`
+ * back.
+ * @param {any} card - makeHeader's result
+ */
+function asReference(card) {
+  const article = card.tagName === "article" ? card : card.children[0]
+  article.properties.className = [...(article.properties.className ?? []), "reference"]
+  return card
+}
+
 /**
  * A relative directive path as the absolute published path it names.
  * The glob's last segment (`*`, `**`) rides along untouched: the
@@ -573,7 +616,7 @@ function trimText(nodes) {
 const skipped = new Set(["pre", "code", "script", "style"])
 
 const writeWalk = createVisitor({
-  block: [internalLink, wikilink, icon, highlight, captionedImage, image, directive, preview, alert],
+  block: [internalLink, anchorLink, externalLink, wikilink, icon, highlight, captionedImage, image, directive, preview, alert],
   skip: (node) => isElement(node) && skipped.has(node.tagName)
 })
 

package/plugins/markdown/codeFence.js

@@ -0,0 +1,56 @@
+/**
+ * A fenced code block's info string: its language, then its meta, which
+ * can carry a title (per Sam, Nov 6):
+ *
+ *     ```md "Hello World.md"
+ *     ```js title="app.js"
+ *
+ * The title is `title="..."` when the meta has one, else the first
+ * quoted string standing on its own, in double or single quotes. The
+ * rest of the meta is the author's, as frontmatter keys vowel doesn't
+ * read are. GitHub ignores the meta, so a titled block still renders
+ * there, without its title. `title="..."` is Docusaurus', Astro's and
+ * rehype-pretty-code's spelling; the bare string is Vowel's short form,
+ * which rules out Expressive Code's meaning for one (mark this text).
+ *
+ * Free of node builtins: the editor may need it.
+ */
+
+const KEYED = /(?:^|\s)title=(?:"([^"]*)"|'([^']*)')(?=\s|$)/
+const BARE = /(?:^|\s)(?:"([^"]*)"|'([^']*)')(?=\s|$)/
+
+/**
+ * The fence as micromark split it, at the first whitespace, read again.
+ * A quoted first word is not a language: in ```` ```"notes.txt" ````
+ * micromark's language is `"notes.txt"`, and the block has none.
+ * @param {string | null | undefined} lang - mdast's `code.lang`
+ * @param {string | null | undefined} meta - mdast's `code.meta`
+ * @returns {{ language: string | null, meta: string | null, title: string | undefined }}
+ */
+export function parseFence(lang, meta) {
+  const quoted = /^["']/.test(lang ?? "")
+  const language = lang && !quoted ? lang : null
+  const rest = (quoted ? [lang, meta].filter(Boolean).join(" ") : meta) || null
+  const match = rest ? KEYED.exec(rest) ?? BARE.exec(rest) : null
+  const title = (match?.[1] ?? match?.[2])?.trim() || undefined
+  return { language, meta: rest, title }
+}
+
+/**
+ * A title written back into a fence, as mdast's `lang` and `meta`:
+ * `title="..."` after a language, the spelling other tools read, and
+ * the bare string without one, since a `title=` would be read as the
+ * language. Split at the first space, as micromark splits it: a `lang`
+ * with a space in it is written with the space escaped. A title with a
+ * double quote in it is in single quotes.
+ * @param {string | null} language
+ * @param {string} title
+ * @returns {{ lang: string | null, meta: string | null }}
+ */
+export function fenceWithTitle(language, title) {
+  const quote = title.includes('"') ? "'" : '"'
+  const quotedTitle = `${quote}${title}${quote}`
+  if (language) return { lang: language, meta: `title=${quotedTitle}` }
+  const [first, ...rest] = quotedTitle.split(/\s+/)
+  return { lang: first, meta: rest.join(" ") || null }
+}

package/plugins/markdown/index.js

@@ -20,6 +20,7 @@ import { toString as hastToString } from 'hast-util-to-string'
 import getMetadata, { imageFromPage, reservedProperties } from "./metadata.js"
 import { isSecretPath, secretRouter, displayPath } from "./../../secretPaths.js"
 import { collectLinks } from "./links.js"
+import { parseFence } from "./codeFence.js"
 import { readWalk } from "./readRules.js"
 import { h } from "hastscript"
 import { mirrorStubs, mirrorWriter, llmsStubs } from "./mirror.js"
@@ -146,8 +147,18 @@ function readFile(source, { api, config }) {
     // is too wide, so the table itself can be a real table at full width
     // (a table that scrolls has to be display: block, which sizes its
     // columns to their content), and a caption has somewhere to go.
+    // A code block with a title (codeFence.js) is in one too, the title
+    // as its caption. One without stays a bare <pre>.
     handlers: {
-      table: (state, node) => h("figure", [defaultHandlers.table(state, node)])
+      table: (state, node) => h("figure.table", [defaultHandlers.table(state, node)]),
+      code: (state, node) => {
+        const fence = parseFence(node.lang, node.meta)
+        const pre = defaultHandlers.code(state, { ...node, lang: fence.language, meta: fence.meta })
+        if (!fence.title) return pre
+        const figure = h("figure.code", [h("figcaption", fence.title), pre])
+        state.patch(node, figure)
+        return figure
+      }
     },
     // `state.all(node)` converts the children to hast; handing over
     // `node.children` gives the HTML compiler raw *mdast* instead. Plain

package/plugins/markdown/typography.js

@@ -20,7 +20,7 @@
  * @property {string} variable - the custom property in TypographyStyles.css
  * @property {string} label
  * @property {string} [hint]
- * @property {"x" | "ch" | ""} unit - "x" is a multiple of --fontsize-root
+ * @property {"ch" | ""} unit
  * @property {number} min
  * @property {number} max
  * @property {number} step
@@ -29,7 +29,7 @@
 
 /** @type {TypographySetting[]} */
 export const rampSettings = [
-  { key: "heading-size", variable: "--fontsize-delta", label: "Heading size", hint: "How much larger h1 is than body text", unit: "x", min: 0.25, max: 4, step: 0.05, default: 2 },
+  { key: "heading-size", variable: "--fontsize-scale", label: "Heading size", hint: "How much larger h1 is than body text, as a multiple of it", unit: "", min: 0.25, max: 4, step: 0.05, default: 1.5 },
   { key: "heading-size-decay", variable: "--fontsize-decay", label: "Size decay", hint: "Higher makes subheadings smaller", unit: "", min: 0.5, max: 6, step: 0.1, default: 3 },
   { key: "h1-letter-spacing", variable: "--letterspacing-h1", label: "h1 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: -0.01 },
   { key: "h6-letter-spacing", variable: "--letterspacing-h6", label: "h6 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: 0 },
@@ -49,15 +49,15 @@ function themeSettings(theme) {
 }
 
 /**
- * A ramp setting's value as CSS, clamped to its range. "x" is a multiple
- * of the root size, so headings follow the root's clamp() up and down.
+ * A ramp setting's value as CSS, clamped to its range. `heading-size` is
+ * a plain number, `--fontsize-scale`, which the sheet multiplies by the
+ * root size, so headings follow the root's clamp() up and down.
  * @param {TypographySetting} setting
  * @param {number} value
  */
 function rampValue(setting, value) {
   const clamped = Math.min(setting.max, Math.max(setting.min, value))
   const number = String(Number(clamped.toFixed(4)))
-  if (setting.unit === "x") return `calc(${number} * var(--fontsize-root))`
   return `${number}${setting.unit}`
 }