vowel 0.7.3 → 0.7.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vowel",
   "type": "module",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "engines": {
     "node": ">=26"
   },

package/plugins/atproto/body.js

@@ -5,6 +5,7 @@ import { gfmFootnoteToMarkdown } from "mdast-util-gfm-footnote"
 import { gfmTaskListItemToMarkdown } from "mdast-util-gfm-task-list-item"
 import { toText } from "hast-util-to-text"
 import { emojiFor } from "../markdown/emoji.js"
+import { alertLabel } from "../html/editor/directives.js"
 
 /**
  * A page's body as a record carries it, from the rendered
@@ -17,7 +18,8 @@ import { emojiFor } from "../markdown/emoji.js"
  *   and footnotes vowel itself reads. Links and images are absolute; an
  *   image links to its copy on the site. An icon is its emoji, or its
  *   shortcode as text. A listing is a list of links. A hashtag is a link
- *   whose text keeps its `#`. No title: it is outside the section.
+ *   whose text keeps its `#`. An alert is GFM's (`> [!NOTE]`). No
+ *   title: it is outside the section.
  * - **Rich text** (`richTextBody`), for a `text` field with `facets`
  *   beside it: plain text, and a facet for each link, hashtag and mark
  *   the lexicon has a feature for. The rest is dropped, images included.
@@ -181,7 +183,8 @@ function block(node, base) {
   if (/^h[1-6]$/.test(tag)) return [{ type: "heading", depth: Number(tag[1]), children: trimPhrasing(phrasing(node.children ?? [], base)) }]
   if (tag === "hr") return [{ type: "thematicBreak" }]
   if (tag === "picture") return [paragraph([node], base)]
-  if (tag === "blockquote" || hasClass(node, "markdown-alert")) return [{ type: "blockquote", children: blocks(node.children ?? [], base) }]
+  if (tag === "aside" && hasClass(node, "alert")) return [alert(node, base)]
+  if (tag === "blockquote") return [{ type: "blockquote", children: blocks(node.children ?? [], base) }]
   if (tag === "pre") {
     const code = (node.children ?? []).find(child => is(child, "code")) ?? node
     const language = classes(code).find(name => name.startsWith("language-"))?.slice("language-".length)
@@ -193,6 +196,30 @@ function block(node, base) {
   return blocks(node.children ?? [], base)
 }
 
+/**
+ * An alert, `<aside class="alert note">` with its heading first, back in
+ * GFM's form: `> [!NOTE]`, then the text on the next line. A heading the
+ * author wrote stays on the marker's line (`> [!NOTE] How to render`,
+ * Obsidian's title, which vowel reads too); the default one, the type in
+ * sentence case, is left off. The marker is raw `html` so that it is
+ * not escaped as a link reference.
+ * @param {any} node
+ * @param {string} base
+ */
+function alert(node, base) {
+  const type = classes(node).find(name => name !== "alert") ?? "note"
+  const [first, ...rest] = (node.children ?? []).filter(child => child.type === "element")
+  const hasHeading = /^h[1-6]$/.test(first?.tagName ?? "")
+  const title = hasHeading && toText(first).trim() !== alertLabel(type) ? trimPhrasing(phrasing(first.children ?? [], base)) : []
+  const marker = [{ type: "html", value: `[!${type.toUpperCase()}]` }, ...(title.length ? [{ type: "text", value: " " }, ...title] : [])]
+  const body = blocks(hasHeading ? rest : [first, ...rest].filter(child => child), base)
+  const [lead, ...after] = body
+  const children = lead?.type === "paragraph"
+    ? [{ ...lead, children: [...marker, { type: "text", value: "\n" }, ...lead.children] }, ...after]
+    : [{ type: "paragraph", children: marker }, ...body]
+  return { type: "blockquote", children }
+}
+
 /** @param {any} node @param {string} base */
 function list(node, base) {
   const items = (node.children ?? []).filter(child => is(child, "li"))

package/plugins/html/index.js

@@ -13,7 +13,7 @@ import { gfmTable } from 'micromark-extension-gfm-table'
 import { gfmTableFromMarkdown } from 'mdast-util-gfm-table'
 import { h } from 'hastscript'
 import { readFileSync } from "fs"
-import { testURL, testHashtags, createHashtagPage, labelFromName, isPageWithoutFile, pageClasses, hashtagRegexSingle, imageSizes } from "./../../utils.js"
+import { testURL, testHashtags, createHashtagPage, labelFromName, isPageWithoutFile, pageClasses, hashtagRegexSingle, imageSizes, mirrorPath } from "./../../utils.js"
 import extractDate from "./../../extractDate.js"
 import { reservedProperties, hiddenProperties } from "./../markdown/metadata.js"
 import { toString as hastToString } from 'hast-util-to-string'
@@ -538,6 +538,18 @@ function writeFile(target, { settings, api, config }) {
     )
   }
 
+  // The page's markdown mirror (markdown/mirror.js), linked only while
+  // it exists. A tracked read: the page is rebuilt when its mirror is
+  // declared or removed, and not when the mirror is rewritten.
+  const mirror = api.target(mirrorPath(target.path))
+  if (mirror) {
+    treeHead.children.push(h("link", {
+      rel: "alternate",
+      type: "text/markdown",
+      href: "/" + mirror.path.split(path.sep).join("/")
+    }))
+  }
+
   // The page's AT Protocol record, for readers that verify a document
   // against its site: standard.site's convention, so only for a
   // site.standard.document, and only for a page that can be one - it

package/plugins/markdown/frontmatter.js

@@ -69,6 +69,7 @@ const EXPECTED = {
   aliases: "strings",
   status: "status",
   html_file: "boolean",
+  markdown_mirror: "boolean",
   rss_item: "boolean",
   sitemap_item: "boolean",
   global_nav_item: "boolean",

package/plugins/markdown/index.js

@@ -21,6 +21,7 @@ import { isSecretPath, secretRouter, displayPath } from "./../../secretPaths.js"
 import { collectLinks } from "./links.js"
 import { readWalk } from "./readRules.js"
 import { h } from "hastscript"
+import { mirrorStubs, mirrorWriter } from "./mirror.js"
 
 import { styleText } from "node:util"
 
@@ -233,6 +234,11 @@ function settingsContribution(metadata, filePath, log) {
   if (metadata.fm_slogan !== undefined) {
     log?.("warn", `${filePath}: \`slogan:\` in a settings file does nothing - a slogan belongs to a page, e.g. home.md`)
   }
+  // Mirrors are declared by an enumerator, which sees the root's
+  // settings only.
+  if (metadata.markdown_mirror !== undefined && filePath !== "settings.md") {
+    log?.("warn", `${filePath}: \`markdown_mirror:\` works only in the root settings.md or in a page's frontmatter`)
+  }
   const declared = Object.entries(metadata)
     .filter(([key]) => key.startsWith("fm_") || reservedProperties.includes(key))
   return {
@@ -242,19 +248,6 @@ function settingsContribution(metadata, filePath, log) {
   }
 }
 
-/**
- * The only markdown target vowel produces is settings.md itself (every
- * other .md file is routed to .html), so this passes its source text
- * through untouched - the panel edits the real file, not a rendering of
- * it.
- * @type {Votive.ProcessorWrite}
- */
-function writeMarkdown(target) {
-  return {
-    data: target.data,
-    encoding: "utf-8"
-  }
-}
 
 
 
@@ -491,8 +484,7 @@ const readMarkdown = {
   router,
   createStubs,
   expandStubs,
-  readFile,
-  writeFile: writeMarkdown
+  readFile
 }
 
 
@@ -500,7 +492,7 @@ const readMarkdown = {
 /** @type {Votive.VotivePlugin} */
 const vowelMarkdownPlugin = {
   name: "vowel",
-  processors: [readMarkdown]
+  processors: [readMarkdown, mirrorStubs, mirrorWriter]
 }
 
 export default vowelMarkdownPlugin

package/plugins/markdown/metadata.js

@@ -79,6 +79,7 @@ export const reservedProperties = [
   "rss_item",
   "sitemap_item",
   "html_file",
+  "markdown_mirror",
   "global_nav_item",
   "local_nav_item",
   "theme",

package/plugins/markdown/mirror.js

@@ -0,0 +1,121 @@
+import path from "node:path"
+import { contentSection } from "../xml/entryContent.js"
+import { markdownBody } from "../atproto/body.js"
+import { isMirrored } from "../../utils.js"
+
+/** @import * as Votive from "votive" */
+
+/**
+ * A page's markdown mirror: `/blog/post.md` beside `/blog/post`, the post
+ * as the reader sees it, in portable markdown. Off by default. The root
+ * settings.md's `markdown_mirror: true` mirrors every page, and a page's
+ * own `markdown_mirror` overrides it; a page with `html_file: false`
+ * is mirrored only when it asks itself, which makes a page whose only
+ * file is its markdown.
+ *
+ * A mirror is a stub of its own source type, `.markdownmirror`, so the
+ * markdown processor never reads it as a page. Its stub path is the
+ * page's *target* path, which routing has already lowercased and
+ * hashed, so a secret page's mirror sits beside its hashed url. A page
+ * that stops being mirrored is no longer declared, and votive removes
+ * its mirror and the file.
+ *
+ * The enumerator sees only the root's settings, so a subfolder's
+ * settings.md cannot switch mirrors (the markdown read warns).
+ * @type {Votive.ProcessorStubs}
+ */
+function createStubs({ api, settings }) {
+  const siteMirrors = settings.lastNonNull("markdown_mirror") === true
+
+  // Off by default, and then only a page that asks for its own mirror
+  // can have one: one filtered query rather than every page on every pass.
+  const candidates = siteMirrors
+    ? api.targets({ folder: "", recursive: true })
+    : api.targets({ folder: "", recursive: true, query: { markdown_mirror: true } })
+
+  const pages = candidates.filter(page => isMirrored(page, siteMirrors))
+  return pages.map(page => ({
+    path: page.path.replace(/\.html$/, ".markdownmirror"),
+    params: { page: page.path }
+  }))
+}
+
+/** @type {Votive.ProcessorExpand} */
+function expandStubs({ params }) {
+  return { text: params.page }
+}
+
+/**
+ * A long date in English, as the page shows it, read in UTC: a date is
+ * stored as UTC midnight, and local time west of UTC is the day before.
+ * @param {string} iso
+ */
+function longDate(iso) {
+  const date = new Date(iso)
+  if (isNaN(Number(date))) return undefined
+  return date.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" })
+}
+
+/**
+ * The mirror is made from the page's rendered `section#content`, not
+ * from the author's source, whose wikilinks, listing directives and
+ * `:icons:` mean nothing outside vowel. The page is a tracked read, so
+ * re-rendering it rewrites its mirror.
+ *
+ * On a pass that writes the mirror before its page, the page's `data` is
+ * still its markdown and has no `section#content`. Then nothing is
+ * written: the page's write stores its HTML, which restales the mirror,
+ * and the same pass writes it again.
+ * @type {Votive.ProcessorWrite}
+ */
+function writeMirror(target, { api, settings }) {
+  const page = api.target(target.metadata.markdown_mirror_of)
+  if (!page) return
+
+  const section = contentSection(page.data)
+  if (!section) return
+
+  // A page without a file has no url of its own, so its mirror names
+  // itself.
+  const ownURL = "/" + String(target.path).split(path.sep).join("/")
+  const pagePath = page.write === false ? ownURL : page.metadata.prettyURL
+  const domain = settings.lastNonNull("fm_domain")
+  const origin = domain ? (String(domain).startsWith("http") ? String(domain) : "https://" + domain) : undefined
+  const url = origin ? new URL(pagePath, origin).href : pagePath
+
+  const title = page.metadata.title
+  const date = page.metadata.date ? longDate(page.metadata.date) : undefined
+  const byline = [date, url].filter(part => part).join(" · ")
+  const body = markdownBody(section, url)
+
+  const parts = [title ? `# ${title}` : undefined, byline, body].filter(part => part)
+  return { data: parts.join("\n\n") + "\n" }
+}
+
+/**
+ * The stub's processor. Its router puts `blog/post.markdownmirror` at
+ * `blog/post.md`.
+ * @type {Votive.VotiveProcessor}
+ */
+const mirrorStubs = {
+  extensions: [".markdownmirror"],
+  format: "text",
+  router: ({ dir, name }) => ({ dir, name, ext: ".md" }),
+  createStubs,
+  expandStubs,
+  readFile: (source) => ({ data: "", metadata: { markdown_mirror_of: source.text } })
+}
+
+/**
+ * The only processor that writes `.md` targets. It reads nothing, so it
+ * needs no format: every `.md` source is the markdown processor's. A
+ * write is matched on the target's extension, so a second `writeFile`
+ * for `.md` would run on every mirror too.
+ * @type {Votive.VotiveProcessor}
+ */
+const mirrorWriter = {
+  extensions: [".md"],
+  writeFile: writeMirror
+}
+
+export { mirrorStubs, mirrorWriter }

package/stylesheets/DefaultStyles.css

@@ -614,78 +614,78 @@
 			display: none;
 		}
 	}
-}
-
-/* footer */
 
-footer {
+	/* footer */
 
-	text-align: center;
-	display: flex;
-	flex-direction: column;
-	align-items: center;
-	gap: 2lh;
+	footer {
 
-	nav ul {
-		list-style: none;
-		padding: 0;
+		text-align: center;
 		display: flex;
-		gap: 1ch;
+		flex-direction: column;
+		align-items: center;
+		gap: 2lh;
 
-		img {
-			height: 1em;
-			width: auto;
+		nav ul {
+			list-style: none;
+			padding: 0;
+			display: flex;
+			gap: 1ch;
+
+			img {
+				height: 1em;
+				width: auto;
+			}
 		}
-	}
 
-	section {
-		display: block;
-	}
+		section {
+			display: block;
+		}
 
-	a {
+		a {
 
-		&,
-		&:visited {
+			&,
+			&:visited {
 
-			color: var(--color-link-body);
-		}
+				color: var(--color-link-body);
+			}
 
-		&:hover {
-			color: var(--color-link-hover-menu);
+			&:hover {
+				color: var(--color-link-hover-menu);
+			}
 		}
+
 	}
 
-}
+	/* homepage */
+	@media (min-width: 140rch) {
+		body.page_home {
+			grid-template-columns: 1fr 15rch 70rch 15rch 1fr;
+		}
+	}
 
-/* homepage */
-@media (min-width: 140rch) {
 	body.page_home {
-		grid-template-columns: 1fr 15rch 70rch 15rch 1fr;
-	}
-}
 
-body.page_home {
 
+		/*
+			The homepage's slogan is the hero
+		*/
+		main>[itemprop="slogan"] {
+			font-size: 4em;
+			font-weight: bold;
+			padding-block: 0.5lh;
 
-	/*
-		The homepage's slogan is the hero
-	*/
-	main>[itemprop="slogan"] {
-		font-size: 4em;
-		font-weight: bold;
-		padding-block: 0.5lh;
 
+		}
 
-	}
+		/*
+			Hide breadcrumbs
+		*/
+		[aria-label=Breadcrumbs],
+		[aria-label=Contents],
+		&>aside>nav,
+		&>main>h1 {
+			display: none;
+		}
 
-	/*
-		Hide breadcrumbs
-	*/
-	[aria-label=Breadcrumbs],
-	[aria-label=Contents],
-	&>aside>nav,
-	&>main>h1 {
-		display: none;
 	}
-
-}
+}

package/utils.js

@@ -171,6 +171,32 @@ export function isPageWithoutFile(target) {
   return target.write === false && target.metadata?.html_file === false
 }
 
+/**
+ * Whether a page has a markdown mirror (plugins/markdown/mirror.js).
+ * The root settings.md's `markdown_mirror` switches every page, and the
+ * page's own key overrides it. A page without a file is mirrored only
+ * when it asks itself: `html_file: false` used to mean "published
+ * nowhere", and switching mirrors on for a site must not publish it.
+ * Another virtual page (`status: deleted`) is never mirrored.
+ * @param {any} page
+ * @param {boolean} siteMirrors - the root settings.md's `markdown_mirror`
+ */
+export function isMirrored(page, siteMirrors) {
+  if (page.extension !== ".html") return false
+  const own = page.metadata?.markdown_mirror
+  if (isPageWithoutFile(page)) return own === true
+  if (page.write === false) return false
+  return typeof own === "boolean" ? own : siteMirrors
+}
+
+/**
+ * Where a page's mirror is: `blog/post.html` → `blog/post.md`.
+ * @param {string} pagePath - a stored target path
+ */
+export function mirrorPath(pagePath) {
+  return pagePath.replace(/\.html$/, ".md")
+}
+
 /**
  * listPages, plus pages without a file: for listings, cards and the
  * feed, which can show a page without linking to it.