vowel 0.7.1-beta.0 → 0.7.3

package/plugins/markdown/metadata.js

@@ -1,10 +1,54 @@
 import { toString as mdastToString } from 'mdast-util-to-string'
 import extractDate, { dateSpan } from "./../../extractDate.js"
-import { testURL, toTitleCase } from "./../../utils.js"
+import { testURL, labelFromName } from "./../../utils.js"
 import path from "node:path"
 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
@@ -35,12 +79,11 @@ export const reservedProperties = [
   "rss_item",
   "sitemap_item",
   "html_file",
-  "global_menu_item",
-  "local_menu_item",
+  "global_nav_item",
+  "local_nav_item",
   "theme",
   "logo",
-  "wordmark",
-  "breadcrumb"
+  "wordmark"
 ]
 
 /**
@@ -50,7 +93,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
@@ -72,10 +115,10 @@ export function normalizeHeadingLevels(tree) {
 }
 
 /**
- * Marks a recognized date in place so it renders as <time> without moving
- * out of the content. The editor reads the element's text back, so the
- * author's own wording survives the round trip and the markup is simply
- * re-inferred on the next build.
+ * Marks a recognized date so it renders as <time>, keeping the author's
+ * wording. The editor reads the element's text back, so that wording
+ * survives the round trip and the markup is simply re-inferred on the
+ * next build.
  * @param {object} paragraph
  * @param {Date} date
  */
@@ -88,44 +131,59 @@ function markAsTime(paragraph, date) {
 }
 
 /**
- * Recognizable data that may precede the content. Each block is recorded
- * where the author placed it and never relocated - only the title is
- * hoisted (see findTitleNode). Adding another inferred property later (an
- * ISBN, say) means adding a branch here, not new plumbing.
+ * Recognizable data that may precede the content. A block is data only
+ * when the property it would fill is still empty: a date line on a page
+ * whose frontmatter has a `date:`, or a second date line, is content,
+ * and the scan stops there (per Sam). Returns what the block is: "date"
+ * or "image" for natural metadata, which the html plugin lifts out of
+ * the content and renders with the page's metadata (the source is never
+ * changed); "skip" for a line that is neither metadata nor content (a
+ * listing, a bare url); false for content. Adding another inferred
+ * property later (an ISBN, say) means adding a branch here, not new
+ * plumbing.
  *
  * @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 children = block.children.filter(child => !isComment(child))
+  const [child] = children
 
-  const [child] = block.children
+  const imageFilled = Boolean(metadata.fm_image || metadata.inferred_image)
 
-  if (child.type === "image") {
-    metadata.inferred_image = child.url
+  // 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 = imageFromPage(child.url, folder)
     metadata.inferred_alt_text = child.alt
-    return true
+    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
   // must not become the page's description, which is what a section
   // index's own listing line was doing. Same test as writeRules'
   // directive rule.
-  if (child.type === "text" && /^(\/|\.\.?\/)\S*$/.test(text.trim())) return true
+  if (child.type === "text" && /^(\/|\.\.?\/)\S*$/.test(text.trim())) return "skip"
 
   if (testURL(text)) {
     const url = new URL(text)
     if (text.match(/\.(jpeg|jpg|png)$/)) {
+      if (imageFilled) return false
       metadata.inferred_image = url
     } else {
       metadata.inferred_link = url
     }
-    return true
+    return "skip"
   }
 
   // A date is a property of the page only when the author wrote it as
@@ -144,12 +202,28 @@ function recognizeData(block, metadata) {
 
   const date = extractDate(text)
   if (!date) return false
+  if (metadata.fm_date || metadata.inferred_date) return false
 
   // Stored as ISO, like a frontmatter date (frontmatter.js, toISODate):
   // one format in the column, which sorts lexically.
   metadata.inferred_date = toISODate(date)
   markAsTime(block, date)
-  return true
+  return "date"
+}
+
+/**
+ * Marks a block as natural metadata - written in the text, not the
+ * frontmatter - for the html plugin to lift out of the content
+ * (`data-metadata`, which it removes): "date", "image", "description",
+ * or "end" for the rule that closed the description, which renders as
+ * nothing. A description is marked as one where it is rendered.
+ * @param {object} block
+ * @param {"date" | "image" | "description" | "end"} kind
+ */
+function markAsNatural(block, kind) {
+  const itemprop = kind === "description" ? { itemprop: "description" } : {}
+  const hProperties = { ...block.data?.hProperties, ...itemprop, dataMetadata: kind }
+  block.data = { ...block.data, hProperties }
 }
 
 /**
@@ -201,19 +275,37 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
 
   const titleNode = findTitleNode(tree)
   if (titleNode) {
-    metadata.inferred_title = mdastToString(titleNode) || toTitleCase(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, folder)
+    if (recognized === "skip") continue
+    if (recognized) {
+      markAsNatural(block, recognized)
+      continue
+    }
 
-  for (const block of blocks) {
-    const recognized = recognizeData(block, metadata)
-    if (recognized) continue
+    // One paragraph and then a rule: the author ended their metadata
+    // with the rule, so the paragraph *is* the description - stated,
+    // not guessed, so it outranks a slogan. With a `description:` in the
+    // frontmatter it is an ordinary paragraph, and the rule an ordinary
+    // rule. (`text` then `---` on the next line is a heading in
+    // 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 = 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
   }
 
@@ -229,7 +321,14 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
   // sees, so it is the one place the salt has to be stripped.
   const pathInfo = path.parse(displayPath(filePath))
 
-  metadata.inferred_label = toTitleCase(pathInfo.name)
+  // A date the author wrote wins; failing that, the one the path spells
+  // (`journal/2024/april/1.md`).
+  if (!metadata.fm_date && !metadata.inferred_date) {
+    const date = pathDate(displayPath(filePath))
+    if (date) metadata.inferred_date = toISODate(date)
+  }
+
+  metadata.inferred_label = labelFromName(pathInfo.name)
 
   // What a [[wikilink]] matches, the way Obsidian matches: the filename
   // without its extension, case-insensitively, plus any `aliases:` the
@@ -283,7 +382,8 @@ function selectMetadata(metadata) {
 
   const description =
     metadata.fm_description
-    || metadata.fm_tagline
+    || metadata.declared_description
+    || metadata.fm_slogan
     || metadata.inferred_description
 
   if (description) {

package/plugins/markdown/typography.js

@@ -9,7 +9,7 @@
 // the document for live preview, so preview and build cannot disagree.
 //
 // No bundled fonts, and no font setting: a family is CSS - the author
-// sets `--font-sans-brand` (and the @font-face behind it) in their own
+// sets `--fontfamily-sans-brand` (and the @font-face behind it) in their own
 // stylesheet, where the sheet's stacks put a system fallback after it.
 // Fonts by url is tasks/2-in-progress/load-fonts.md. Free of node
 // builtins.
@@ -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 --font-size-root
+ * @property {"x" | "ch" | ""} unit - "x" is a multiple of --fontsize-root
  * @property {number} min
  * @property {number} max
  * @property {number} step
@@ -29,14 +29,14 @@
 
 /** @type {TypographySetting[]} */
 export const rampSettings = [
-  { key: "heading-size", variable: "--font-size-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-decay", variable: "--font-size-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: "--letter-spacing-h1", label: "h1 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: -0.01 },
-  { key: "h6-letter-spacing", variable: "--letter-spacing-h6", label: "h6 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: 0 },
-  { key: "letter-spacing-decay", variable: "--letter-spacing-decay", label: "Spacing decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 },
-  { key: "h1-weight", variable: "--font-weight-h1", label: "h1 weight", unit: "", min: 100, max: 900, step: 10, default: 800 },
-  { key: "h6-weight", variable: "--font-weight-h6", label: "h6 weight", unit: "", min: 100, max: 900, step: 10, default: 600 },
-  { key: "weight-decay", variable: "--font-weight-decay", label: "Weight decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 }
+  { 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-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 },
+  { key: "letter-spacing-decay", variable: "--letterspacing-decay", label: "Spacing decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 },
+  { key: "h1-weight", variable: "--fontweight-h1", label: "h1 weight", unit: "", min: 100, max: 900, step: 10, default: 800 },
+  { key: "h6-weight", variable: "--fontweight-h6", label: "h6 weight", unit: "", min: 100, max: 900, step: 10, default: 600 },
+  { key: "weight-decay", variable: "--fontweight-decay", label: "Weight decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 }
 ]
 
 /**
@@ -57,7 +57,7 @@ function themeSettings(theme) {
 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(--font-size-root))`
+  if (setting.unit === "x") return `calc(${number} * var(--fontsize-root))`
   return `${number}${setting.unit}`
 }
 

package/plugins/styles/index.js

@@ -4,7 +4,7 @@ import { styleText } from "node:util"
 import { transform } from "lightningcss"
 import { hash } from "node:crypto"
 import { resolveTheme, themeStylesheets, themeKey } from "./theme.js"
-import { themeColorSchemeCSS } from "../markdown/colorScheme.js"
+import { themeColorSchemeCSS, colorParams } from "../markdown/colorScheme.js"
 import { typographyCSS } from "../markdown/typography.js"
 
 /** @import * as Votive from "votive" */
@@ -54,7 +54,7 @@ function createStubs({ api, settings }) {
     return themeStylesheets(theme, rootTheme).map(sheet => {
       // Generated sheets carry the part of the theme they are generated
       // from, so they re-expand exactly when that part changes.
-      if (sheet.startsWith("colors")) return { path: sheet, params: { colors: config.colors ?? null } }
+      if (sheet.startsWith("colors")) return { path: sheet, params: colorParams(config) }
       if (sheet.startsWith("type")) return { path: sheet, params: { theme: config } }
       return { path: sheet }
     })
@@ -80,8 +80,8 @@ function expandStubs({ path: sourcePath, params }) {
     // Reports and falls back rather than throwing: a site with unusable
     // colours should lose its palette, not its build.
     return {
-      text: themeColorSchemeCSS(params?.colors, error => (
-        console.warn(`${styleText("dim", "build: ")}${styleText("yellow", `ignoring theme.colors - ${error.message}`)}`)
+      text: themeColorSchemeCSS(params ?? {}, error => (
+        console.warn(`${styleText("dim", "build: ")}${styleText("yellow", error.message)}`)
       ))
     }
   }

package/plugins/xml/index.js

@@ -1,5 +1,5 @@
 import xml from "xml"
-import { listPages } from "./../../utils.js"
+import { showPages, isPageWithoutFile } from "./../../utils.js"
 import { entryContent } from "./entryContent.js"
 
 /** @import * as Votive from "votive" */
@@ -134,7 +134,10 @@ const processor = {
       // the entries kept read it. `feed_limit` in settings.md raises or
       // lowers it.
       const limit = Number(settings.lastNonNull("fm_feed_limit")) || DEFAULT_FEED_LIMIT
-      const pages = listPages(api, {
+      // A page with no file (`html_file: false`) is an entry too, with
+      // its body and no <link>: Atom needs an <id> and content, not a
+      // link, which is what makes a feed-only post possible.
+      const pages = showPages(api, {
         query: {
           "!": {
             rss_item: false
@@ -194,21 +197,25 @@ const processor = {
 
       feed.push(
         ...pages.map((page) => {
+          // The url the page has, or would have: an Atom <id> is an
+          // identifier, so a page without a file keeps the one it would
+          // have, and keeps it if it gets a file later.
           const url = (new URL(page.path, domain)).href
+          const link = isPageWithoutFile(page) ? [] : [{
+            link: {
+              _attr: {
+                rel: 'alternate',
+                href: url
+              }
+            }
+          }]
 
           /** @type {object[]} */
           const entry = [
             {
               title: page.metadata.title
             },
-            {
-              link: {
-                _attr: {
-                  rel: 'alternate',
-                  href: url
-                }
-              }
-            },
+            ...link,
             { id: url },
             { updated: page.metadata.date }
           ];