vowel 0.6.2 → 0.6.4

package/README.md

@@ -9,6 +9,11 @@ See the docs: [vowel.cc](https://vowel.cc).
 
 ## Roadmap
 
+### Priorities
+
+- [ ] Create CONTRIBUTING.md
+- [ ] 
+
 ### Launch checklist
 
 - [x] CLI
@@ -17,14 +22,15 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [x] Route patterns
 - [x] Post list metadata
 - [.] Transaction management
+- [ ] Default 404 pages
 
 - [.] Fixes
   - [x] Global nav sublinks
   - [x] Hot reload
-  - [.] Explicit asset handling
+  - [x] Explicit asset handling
   - [.] Change "job" to "resources"
     - [.] ReadResource types
-  - [.] Processor utilities param
+  - [x] Processor utilities param
   - [.] Delete old SQLite logic
   - [.] Make metadata explicit in SQLiteTarget type
   - [x] Add SQLite begin/commit logic
@@ -35,26 +41,27 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [x] Homepage in global nav
   - [x] Metadata in header
   - [x] Page list sort
-  - [.] Limit in sort
+  - [x] Limit in sort
 - [x] Metafiles
   - [x] Robots.txt
   - [x] Sitemap.xml
   - [x] RSS
-  - [ ] 404.html (just make 404.md)
+  - [x] 404.html (just make 404.md)
 - [ ] Markup
-  - [.] Image as figure
+  - [x] Image as figure
   - [x] Admonitions
   - [x] Heading anchors
   - [ ] GFM emoji
   - [ ] Mermaid
   - [x] Slogan
   - [x] TOC
+  - [x] ==mark==
 - [ ] Non-urgent fixes / improvements
   - [ ] Compare metadata on file update
   - [x] Prune/cleanup step
-  - [ ] Dependency type (file, settings, folder)
+  - [x] Dependency type (file, settings, folder)
 - [ ] New systems
-  - [ ] Tags
+  - [x] Tags
   - [ ] External links
   - [ ] Syntax highlighting
   - [ ] Social links
@@ -68,7 +75,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] GetMany "extension" filter
 - [ ] Delete settings logic
 - [ ] Update settings logic
-- [ ] Logical operators for filters
+- [x] Logical operators for filters
 - [ ] Customize menus
 - [ ] More file handling plugins
   - [ ] Fonts
@@ -91,21 +98,20 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [ ] Styles
     - [x] .css
     - [x] Bundling
-  - [ ] PDFs
-  - [ ] Videos
-  - [ ] Arbitrary data
+  - [x] PDFs
+  - [x] Videos
+  - [x] Arbitrary data
 - [x] Add homepage to global nav
 - [x] Page lists
 - [x] Dates
 - [x] robots.txt
 - [x] sitemap.xml
-- [ ] 404.html
+- [x] 404.html
 - [ ] Better URL normalization (see notes)
 - [x] Name casing
 - [x] TUI
   - [x] Create settings.md
     - [x] Site title
-    - [x] Domain
     - [ ] Webmentions
     - [x] Logo
     - [x] Wordmark
@@ -121,7 +127,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [x] Custom CSS
   - [x] styles.css
   - [ ] Any CSS file
-- [ ] Tags
+- [x] Tags
 - [ ] Date format settings
 - [ ] ::mark::
 - [x] Infer images
@@ -136,7 +142,7 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] Handle external links
 - [x] Admonitions
 - [ ] Use hgroup for site title, page title, etc
-- [ ] Images as `<figure>`
+- [x] Images as `<figure>`
 - [ ] Hidden routes
 - [ ] Frontmatter settings
   - [ ] HTML
@@ -156,8 +162,8 @@ See the docs: [vowel.cc](https://vowel.cc).
 - [ ] Image optimization (unpic)
 - [ ] [SVG by mask](https://pqina.nl/blog/set-svg-background-image-fill-color/) and [CSS icons](https://antfu.me/posts/icons-in-pure-css)
 - [ ] WYSIWYG editor
-- [ ] Better signals
-  - [ ] File-written callback
+- [x] Better signals
+  - [x] File-written callback
 - [ ] Themes
 - [ ] Deploy
   - [ ] Cloudflare pages
@@ -173,7 +179,7 @@ See the docs: [vowel.cc](https://vowel.cc).
   - [ ] Image
   - [ ] URL
   - [ ] Date
-- [ ] TOC
+- [x] TOC
 - [ ] Versioning/publishing script
 - [ ] Verify all element types from Obsidian
 - [ ] Order/position/kanban

package/bin.js

@@ -18,7 +18,7 @@ import init from "./index.js"
 /** @param {boolean} verbose */
 async function removeCache(verbose) {
   try {
-    await fs.rm("./.votive.db")
+    await fs.rm(config.databasePath)
     if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "cache cleared")}`)
   } catch (e) {
     if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no database cache found")}`)
@@ -28,7 +28,7 @@ async function removeCache(verbose) {
 /** @param {boolean} verbose */
 async function removeDB(verbose) {
   try {
-    await fs.rm("./output", { recursive: true, force: true })
+    await fs.rm(config.targetFolder, { recursive: true, force: true })
     if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "output cleared")}`)
   } catch (e) {
     if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", "no output cache found")}`)
@@ -190,14 +190,51 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 }
 
 
+/**
+ * Runs one registered command directly and exits - no dev server, no
+ * wizard, no cache-wiping. Reuses the exact handler a live "Publish"
+ * button would trigger over WS (see voot's runCommand/handleCommand) -
+ * this is just the other invocation path for the same registered
+ * function, meant for CI/automated use (e.g. `vowel --command deploy`).
+ * @param {string} name
+ * @param {string} [payloadJSON]
+ */
+async function runCLICommand(name, payloadJSON) {
+  const { runCommand } = await import("voot")
+
+  let payload
+  try {
+    payload = payloadJSON ? JSON.parse(payloadJSON) : undefined
+  } catch (e) {
+    console.error(`--payload must be valid JSON: ${e.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  try {
+    const data = await runCommand(config, name, payload, message => {
+      console.info(message?.message ?? message)
+    })
+    if (data !== undefined) console.info(JSON.stringify(data))
+  } catch (e) {
+    console.error(e?.message || e)
+    process.exitCode = 1
+  }
+}
+
 async function main() {
   const args = parse(process.argv.slice(2))
 
-  const dbExists = await exists(".votive.db")
+  if (args.command) {
+    await runCLICommand(args.command, args.payload)
+    return
+  }
+
+  const dbExists = await exists(config.databasePath)
 
   await removeCache(args.logging === "verbose")
   await removeDB(args.logging === "verbose")
-  await fs.mkdir(config.destinationFolder, { recursive: true })
+  await fs.mkdir(config.targetFolder, { recursive: true })
 
   if (!args.skip && !dbExists) {
     const loading = votive({ ...config, verbose: false })

package/config.js

@@ -1,22 +1,41 @@
+import path from "node:path"
+import { systemDirectoryFor } from "votive/internals"
 import vowelImagesPlugin from "./plugins/images/index.js"
 import vowelStylesPlugin from "./plugins/styles/index.js"
-import vowelMarkdownPlugin from "./plugins/markdown/index.js"
-import vowelRobotsPlugin from "./plugins/robots/index.js"
-import vowelXMLPlugin from "./plugins/xml/index.js"
+import vowelReadMarkdownPlugin from "./plugins/markdown/index.js"
+import vowelWriteRobotsPlugin from "./plugins/robots/index.js"
+import vowelWriteXMLPlugin from "./plugins/xml/index.js"
 import vowelVectorPlugin from "./plugins/vectors/index.js"
 import vowelFontsPlugin from "./plugins/fonts/index.js"
+import vowelWriteHTMLPlugin from "./plugins/html/index.js"
+import vowelURLsPlugin from "./plugins/urls/index.js"
 
 /** @import {VotiveConfig} from "votive" */
+
+const sourceFolder = "."
+
+// Vowel targets non-developer end users (via whatever app embeds it),
+// who could be confused by an `output`/.votive.db/.cache showing up in
+// their project folder - keep all three in an OS-appropriate system
+// directory instead, keyed per-project so multiple Vowel sites never
+// collide. Override any of the three below if you want them back in
+// the project directory (or somewhere else entirely).
+const systemDirectory = systemDirectoryFor(sourceFolder)
+
 export const config = {
-  sourceFolder: ".",
-  destinationFolder: "output",
+  sourceFolder,
+  targetFolder: path.join(systemDirectory, "output"),
+  databasePath: path.join(systemDirectory, ".votive.db"),
+  cacheDirectory: path.join(systemDirectory, ".cache"),
   plugins: [
-    vowelMarkdownPlugin,
+    vowelReadMarkdownPlugin,
     vowelImagesPlugin,
     vowelStylesPlugin,
-    vowelRobotsPlugin,
-    vowelXMLPlugin,
+    vowelWriteRobotsPlugin,
+    vowelWriteXMLPlugin,
     vowelVectorPlugin,
-    vowelFontsPlugin
+    vowelFontsPlugin,
+    vowelURLsPlugin,
+    vowelWriteHTMLPlugin
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vowel",
   "type": "module",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "bin": "bin.js",
   "main": "index.js",
   "scripts": {
@@ -28,6 +28,7 @@
     "hast-util-from-html": "^2.0.3",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
+    "highlight.js": "^11.12.0",
     "js-yaml": "^4.1.0",
     "lightningcss": "^1.32.0",
     "mdast": "^2.3.2",
@@ -37,6 +38,7 @@
     "mdast-util-gfm-strikethrough": "^2.0.0",
     "mdast-util-gfm-table": "^2.0.0",
     "mdast-util-gfm-task-list-item": "^2.0.0",
+    "mdast-util-highlight-mark": "^1.2.2",
     "mdast-util-to-hast": "^13.2.1",
     "mdast-util-to-markdown": "^2.1.2",
     "mdast-util-to-string": "^4.0.0",
@@ -44,10 +46,12 @@
     "micromark-extension-gfm-footnote": "^2.1.0",
     "micromark-extension-gfm-table": "^2.1.1",
     "micromark-extension-gfm-task-list-item": "^2.1.0",
+    "micromark-extension-highlight-mark": "^1.2.0",
     "postcss": "^8.5.9",
     "rehype": "^13.0.2",
     "rehype-document": "^7.0.3",
     "rehype-github-alert": "^1.0.0",
+    "rehype-highlight": "^7.0.2",
     "rehype-parse": "^9.0.1",
     "rehype-preset-minify": "^7.0.1",
     "rehype-slug": "^6.0.0",

package/plugins/deploy-cloudflare/index.js

@@ -0,0 +1,78 @@
+import votive from "votive"
+import { spawn } from "node:child_process"
+
+/**
+ * Publishes a full build to Cloudflare Pages via `wrangler pages deploy`.
+ *
+ * Always runs a complete build first, regardless of whether a dev server
+ * happens to already be running against this config - a command's
+ * context (config, notify) has no reference to a live server's own build
+ * queue, and this needs to behave identically whether triggered from the
+ * CLI (no server at all, see voot's runCommand) or a live "Publish"
+ * button over WS. Modest redundant cost when a dev server IS already
+ * running (bundle() is cheap when nothing's stale), traded for one
+ * deploy command that works the same everywhere.
+ *
+ * Shells out to `wrangler` rather than calling Cloudflare's REST API
+ * directly - Pages deploys require content-hashing every asset and
+ * building a manifest in Cloudflare's specific format, which wrangler
+ * already implements and maintains. `wrangler` reads
+ * CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID from the environment
+ * natively; this never touches credentials itself, and none should ever
+ * be added to `config` (it isn't a place secrets should live).
+ *
+ * @param {any} payload
+ * @param {{ config: import("votive").VotiveConfig & { cloudflareProjectName?: string }, notify: (message: object) => void }} context
+ */
+async function deployToCloudflarePages(payload, { config, notify }) {
+  if (!config.cloudflareProjectName) throw new Error("config.cloudflareProjectName is required to deploy")
+
+  notify({ status: "progress", message: "Building..." })
+
+  const queue = await votive({ ...config, verbose: false })
+  const { runBuffers, runFetches } = await queue()
+
+  // Unlike a dev server's own rebuilds, a deploy needs everything done -
+  // there's no "next edit" to stay responsive for, so these are awaited
+  // fully instead of fired via runDeferred().
+  if (runBuffers) await runBuffers()
+  if (runFetches) await runFetches()
+
+  notify({ status: "progress", message: `Publishing ${config.targetFolder} to Cloudflare Pages...` })
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      "wrangler",
+      ["pages", "deploy", config.targetFolder, "--project-name", config.cloudflareProjectName],
+      { stdio: ["ignore", "pipe", "pipe"] }
+    )
+
+    // Piped, not "inherit" - this can run with no terminal attached at
+    // all (triggered over WS from a browser), so wrangler's own output
+    // has to go through notify() to reach whoever's actually watching.
+    proc.stdout.on("data", chunk => notify({ status: "progress", message: chunk.toString() }))
+    proc.stderr.on("data", chunk => notify({ status: "progress", message: chunk.toString() }))
+
+    proc.on("error", reject) // e.g. wrangler isn't installed
+    proc.on("exit", code => {
+      if (code === 0) resolve({ deployed: true })
+      else reject(new Error(`wrangler exited with code ${code}`))
+    })
+  })
+}
+
+/**
+ * Not part of vowel's default plugin list (see config.js) - deploying to
+ * Cloudflare Pages specifically is an opt-in choice a site adds for
+ * itself, along with its own `cloudflareProjectName`, not something
+ * every vowel site should get by default.
+ * @type {import("votive").VotivePlugin}
+ */
+const vowelDeployCloudflarePlugin = {
+  name: "vowel-deploy-cloudflare",
+  commands: {
+    deploy: deployToCloudflarePages
+  }
+}
+
+export default vowelDeployCloudflarePlugin

package/plugins/fonts/index.js

@@ -2,8 +2,8 @@ import { readFile } from "node:fs/promises"
 /** @import * as Votive from "votive" */
 
 /** @type {Votive.ProcessorWrite} */
-async function writeFile(destination, database, config) {
-  const buffer = await readFile(destination.abstract.filePath)
+async function writeFile(target, settings, api, config) {
+  const buffer = await readFile(target.abstract.filePath)
   return {
     data: buffer,
   }

package/plugins/html/image.js

@@ -0,0 +1,78 @@
+import { testURL, createImagePaths, imageSizes, imageExts } from "./../../utils.js"
+import path from "node:path"
+import { h } from 'hastscript'
+import * as unpic from "unpic"
+
+/** @import * as Votive from "votive" */
+
+/**
+ * @param {string} imagePath
+ * @param {import("votive").PluginAPI} api
+ * @param {string} alt
+ * @param {boolean} [itemprop]
+ */
+function createDynamicImage(imagePath, api, alt, itemprop) {
+  // TODO: Hardcode image height and width
+  const parsed = path.parse(imagePath);
+  const isURL = testURL(imagePath)
+  const isImg = !parsed.ext.search(/^.(png|jpeg|jpg)$/);
+
+  if (isURL) {
+    const parsedImageURL = unpic.parseUrl(imagePath)
+    if (parsedImageURL) {
+
+      const sources = [...imageExts, "jpeg"].map((format, index) => {
+
+        const isImg = index === imageExts.length
+        // TODO: Ignore images that have options already specified
+        const urls = imageSizes.map(size => {
+          return unpic.transformUrl({
+            format: format,
+            url: parsedImageURL.src,
+            provider: parsedImageURL.cdn,
+            width: size
+          })
+        })
+
+        const sizes = urls.map((url, index) => `${url} ${imageSizes[index]}w`).join(", ")
+
+        return h(isImg ? "img" : "source", {
+          type: "image/" + format,
+          srcset: sizes,
+          src: isImg && urls.at(-1),
+          loading: isImg && "lazy",
+          sizes: "100vw",
+          alt: isImg && alt
+        })
+      })
+
+      return h("picture", { itemprop: itemprop && "image" }, sources)
+    }
+  }
+
+  if (!isImg) return
+
+  const relativePath = imagePath.startsWith("/") ? path.relative("/", imagePath) : imagePath
+  const image = api.target(relativePath)
+  if (!image) return
+  const formats = createImagePaths(image.abstract.sourcePath, "./", image.abstract.uuid)
+
+  const sources = formats.map((format, index) => {
+    const isImg = index === formats.length - 1
+
+    const sizes = format.map((size, index) => `/${size} ${imageSizes[index]}w`).join(", ")
+    const type = "image/" + path.extname(format[0]).slice(1)
+    return h(isImg ? "img" : "source", {
+      type,
+      srcset: sizes,
+      loading: isImg && "lazy",
+      src: isImg && "/" + format.at(-1),
+      sizes: "100vw",
+      alt: isImg && alt
+    })
+  })
+
+  return h("picture", { itemprop: itemprop && "image" }, sources)
+}
+
+export default createDynamicImage