vowel 0.8.0 → 0.8.1

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

@@ -8,6 +8,8 @@ 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
@@ -148,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)
   }
 }
 
@@ -247,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
   }
@@ -323,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)]
   }
 }
@@ -419,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)
@@ -455,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
@@ -569,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}`
 }
 

package/stylesheets/DefaultStyles.css

@@ -66,10 +66,29 @@
 		--color-text-hover-panel: light-dark(var(--color-primary-02), var(--color-primary-08));
 		--color-border-hover-panel: light-dark(var(--color-accent-08), var(--color-accent-05));
 
-		/* pre colors */
-		--color-background-pre: light-dark(var(--color-tertiary-09), var(--color-tertiary-02));
-		--color-border-pre: light-dark(var(--color-tertiary-08), var(--color-tertiary-01));
-		--color-text-pre: light-dark(var(--color-tertiary-02), var(--color-tertiary-02));
+		/*
+			pre colors, and the syntax-highlighting sheet's from the
+			palette: the text at the far end from the background, every
+			token one shade in, so each stays above 4.5:1 on the
+			background for any ordinary palette (tests/syntaxColors.js).
+			Comments too, told apart by italics: a shade lighter fell to
+			4.2:1 on a palette from bright colours (#ffcc00, #66ff00).
+		*/
+		--color-background-pre: light-dark(var(--color-tertiary-10), var(--color-tertiary-02));
+		--color-border-pre: light-dark(var(--color-tertiary-08), var(--color-tertiary-02));
+		--color-text-pre: light-dark(var(--color-tertiary-04), var(--color-tertiary-08));
+		--color-comment-pre: light-dark(var(--color-accent-04), var(--color-accent-09));
+		--color-keyword-pre: light-dark(var(--color-primary-04), var(--color-primary-07));
+		--color-function-pre: light-dark(var(--color-secondary-04), var(--color-secondary-07));
+		--color-constant-pre: light-dark(var(--color-info-04), var(--color-info-07));
+		--color-string-pre: light-dark(var(--color-tertiary-04), var(--color-tertiary-08));
+		--color-builtin-pre: light-dark(var(--color-warning-04), var(--color-warning-07));
+		--color-tag-pre: light-dark(var(--color-success-05), var(--color-success-07));
+		--color-list-pre: light-dark(var(--color-warning-05), var(--color-warning-07));
+		--color-inserted-pre: light-dark(var(--color-success-05), var(--color-success-07));
+		--color-background-inserted-pre: light-dark(var(--color-success-07), var(--color-success-05));
+		--color-deleted-pre: light-dark(var(--color-danger-05), var(--color-danger-07));
+		--color-background-deleted-pre: light-dark(var(--color-danger-07), var(--color-danger-05));
 
 		/*
 			alert colors: --color-{element}-alert-{type} for the types the
@@ -484,6 +503,11 @@
 				background: var(--color-background-pre);
 			}
 
+			/* a comment is the text's colour, a shade lighter: italics tell it apart */
+			.token.comment {
+				font-style: italic;
+			}
+
 			blockquote {
 				border-left: 0.5ch solid var(--color-border-body);
 			}