vowel 0.7.1 → 0.7.4

package/plugins/markdown/metadata.js

@@ -6,6 +6,49 @@ import { displayPath } from "../../secretPaths.js"
 import pathDate from "../../pathDate.js"
 import { coerce, parseFrontmatter, toISODate } from "./frontmatter.js"
 
+/**
+ * An HTML comment, or several in a row with nothing else between them.
+ * It stays in the page, but metadata never reads it (per Sam): a
+ * comment is not a title, a date or a description, and it doesn't take
+ * a block's place in the scan for one.
+ * @param {any} node
+ */
+function isComment(node) {
+  return node.type === "html" && /^\s*(?:<!--[\s\S]*?-->\s*)+$/.test(node.value)
+}
+
+/**
+ * A node's text for metadata: mdastToString with its HTML comments left
+ * out, at any depth. Where a comment sat between two words, the spaces
+ * either side of it close up to one.
+ * @param {any} node
+ * @returns {string}
+ */
+function metadataText(node) {
+  if (isComment(node)) return ""
+  if (!node.children) return mdastToString(node)
+  const text = node.children.map(metadataText).join("")
+  if (!node.children.some(isComment)) return text
+  return text.replace(/[ \t]{2,}/g, " ")
+}
+
+/**
+ * An image the page's text names, as the browser resolves it from the
+ * page: `pic.jpg` and `./pic.jpg` are the page's folder's, `../pic.jpg`
+ * its parent's, `/pic.jpg` the root's. Stored as a path from the root,
+ * the way the html write resolves the same image (`fromPage` in
+ * writeRules.js), because a listing card and `og:image` read it from
+ * pages in other folders. An external url is left as written. (A
+ * frontmatter `image:` is a setting-style path instead: `resolvePath`.)
+ * @param {string} url - as written
+ * @param {string} folder - the page's target folder, project-relative ("" at the root)
+ */
+export function imageFromPage(url, folder) {
+  if (/^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//")) return url
+  const base = new URL(folder ? `/${folder.split(path.sep).join("/")}/` : "/", "thismessage://")
+  return decodeURIComponent(new URL(url.replaceAll("#", "%23"), base).pathname)
+}
+
 
 /**
 - menu_item: true | false
@@ -36,6 +79,7 @@ export const reservedProperties = [
   "rss_item",
   "sitemap_item",
   "html_file",
+  "markdown_mirror",
   "global_nav_item",
   "local_nav_item",
   "theme",
@@ -50,7 +94,7 @@ export const reservedProperties = [
  * @param {object} tree
  */
 export function findTitleNode(tree) {
-  const [first] = tree.children.filter(child => child.type !== "yaml")
+  const [first] = tree.children.filter(child => child.type !== "yaml" && !isComment(child))
   if (!first) return null
   if (first.type !== "heading" || first.depth !== 1) return null
   return first
@@ -101,24 +145,29 @@ function markAsTime(paragraph, date) {
  *
  * @param {object} block
  * @param {object} metadata
+ * @param {string} folder - the page's target folder, for a relative image
  * @returns {boolean} whether the block was recognizable data
  */
-function recognizeData(block, metadata) {
+function recognizeData(block, metadata, folder) {
   if (block.type !== "paragraph") return false
-  if (block.children.length !== 1) return false
-
-  const [child] = block.children
+  const children = block.children.filter(child => !isComment(child))
+  const [child] = children
 
   const imageFilled = Boolean(metadata.fm_image || metadata.inferred_image)
 
-  if (child.type === "image") {
+  // An image, alone or with its caption after it on the same line: the
+  // html write makes the pair a <figure> and lifts it whole. The caption
+  // is not a property of the page.
+  if (child?.type === "image") {
     if (imageFilled) return false
-    metadata.inferred_image = child.url
+    metadata.inferred_image = imageFromPage(child.url, folder)
     metadata.inferred_alt_text = child.alt
     return "image"
   }
 
-  const text = mdastToString(block)
+  if (children.length !== 1) return false
+
+  const text = metadataText(block)
 
   // A reference or a listing directive (`/blog/post`, `/blog/**`,
   // `./drafts/*`) is an instruction to the html plugin, not prose - it
@@ -227,16 +276,16 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
 
   const titleNode = findTitleNode(tree)
   if (titleNode) {
-    metadata.inferred_title = mdastToString(titleNode) || labelFromName(path.parse(filePath).name)
+    metadata.inferred_title = metadataText(titleNode).trim() || labelFromName(path.parse(filePath).name)
   }
 
   // Everything up to the first block that is not recognizable data is
   // metadata; that first block is where the content begins, and it also
   // supplies the description.
-  const blocks = tree.children.filter(child => child.type !== "yaml" && child !== titleNode)
+  const blocks = tree.children.filter(child => child.type !== "yaml" && child !== titleNode && !isComment(child))
 
   for (const [index, block] of blocks.entries()) {
-    const recognized = recognizeData(block, metadata)
+    const recognized = recognizeData(block, metadata, folder)
     if (recognized === "skip") continue
     if (recognized) {
       markAsNatural(block, recognized)
@@ -251,13 +300,13 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
     // markdown, not a paragraph and a rule; it takes a blank line.)
     const next = blocks[index + 1]
     if (!metadata.fm_description && block.type === "paragraph" && next?.type === "thematicBreak") {
-      metadata.declared_description = mdastToString(block)
+      metadata.declared_description = metadataText(block).trim()
       markAsNatural(block, "description")
       markAsNatural(next, "end")
       break
     }
 
-    if (!metadata.fm_description) metadata.inferred_description = mdastToString(block)
+    if (!metadata.fm_description) metadata.inferred_description = metadataText(block).trim()
     break
   }
 

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

@@ -311,6 +311,7 @@
 			ul {
 				list-style: none;
 				display: flex;
+				flex-wrap: wrap;
 				gap: 2ch;
 			}
 
@@ -438,6 +439,11 @@
 			}
 		}
 
+		/* the page's own image, beside its title, as well as the content's */
+		img {
+			border-radius: var(--borderradius-tight);
+		}
+
 		/* content */
 
 		section#content {
@@ -454,10 +460,6 @@
 				}
 			}
 
-			img {
-				border-radius: var(--borderradius-tight);
-			}
-
 			mark,
 			code {
 				padding: 0.1cap 0.5ch;
@@ -612,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/stylesheets/TypographyStyles.css

@@ -334,15 +334,15 @@
 		&>section {
 			margin-top: 1lh;
 		}
-	}
-
-	/* content */
-	section {
 
-		/* image caption space */
+		/* image caption space: the page's own captioned image, beside its title, as well as the content's */
 		figure {
 			gap: 1lh;
 		}
+	}
+
+	/* content */
+	section {
 
 		/* list spacing */
 		ul,

package/utils.js

@@ -23,26 +23,6 @@ export function createImagePath({ targetFilePath, size, ext, targetDirectory, uu
   })
 }
 
-/**
- * @param {string} targetFilePath
- * @param {string} targetDirectory
- * @param {string} uuid
- */
-export function createImagePaths(targetFilePath, targetDirectory, uuid) {
-  const defaultExt = path.extname(targetFilePath)
-  return [...imageExts, defaultExt].map(ext => {
-    return imageSizes.map(size => {
-      return createImagePath({
-        targetFilePath,
-        size,
-        ext,
-        targetDirectory,
-        uuid
-      })
-    })
-  })
-}
-
 /** @param {string} text */
 export function testURL(text) {
   if (text.match(/^https?:\/\/[\S]+$/)) {
@@ -191,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.