vowel 0.7.1-beta.0 → 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Littlefair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,245 +2,47 @@
 
 *Markdown websites in milliseconds*
 
-- Bundled with [Votive](https://github.com/samlfair/votive)
-- Served with [Votive](https://github.com/samlfair/votive)'s dev server
-
-See the docs: [vowel.cc](https://vowel.cc).
-
-## Roadmap
-
-### Priorities
-
-- [ ] Create CONTRIBUTING.md
-- [ ] 
-
-### Launch checklist
-
-- [x] CLI
-- [x] Docs
-- [x] Classes
-- [x] Route patterns
-- [x] Post list metadata
-- [.] Transaction management
-- [ ] Default 404 pages
-
-- [.] Fixes
-  - [x] Global nav sublinks
-  - [x] Hot reload
-  - [x] Explicit asset handling
-  - [.] Change "job" to "resources"
-    - [.] ReadResource types
-  - [x] Processor utilities param
-  - [.] Delete old SQLite logic
-  - [.] Make metadata explicit in SQLiteTarget type
-  - [x] Add SQLite begin/commit logic
-  - [.] Remove "loadDatabase"
-  - [.] Check all types
-- [.] File handling
-  - [x] CSS prefixing
-  - [x] Homepage in global nav
-  - [x] Metadata in header
-  - [x] Page list sort
-  - [x] Limit in sort
-- [x] Metafiles
-  - [x] Robots.txt
-  - [x] Sitemap.xml
-  - [x] RSS
-  - [x] 404.html (just make 404.md)
-- [ ] Markup
-  - [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
-  - [x] Dependency type (file, settings, folder)
-- [ ] New systems
-  - [x] Tags
-  - [ ] External links
-  - [ ] Syntax highlighting
-  - [ ] Social links
-
-### High priority
-
-- [x] Global nav
-- [x] Breadcrumbs
-- [x] Page classes
-- [ ] GetMany "path exists" filter
-- [ ] GetMany "extension" filter
-- [ ] Delete settings logic
-- [ ] Update settings logic
-- [x] Logical operators for filters
-- [ ] Customize menus
-- [ ] More file handling plugins
-  - [ ] Fonts
-    - [x] .woff
-    - [x] .woff2
-    - [x] .ttf
-    - [x] .otf
-    - [ ] Handling
-  - [ ] Images
-    - [x] .png
-    - [x] .jpg
-    - [x] .jpeg
-    - [x] .webp
-    - [x] .gif
-    - [ ] Formatting
-  - [ ] Icons
-    - [x] .ico
-  - [ ] Vectors
-    - [x] .svg
-  - [ ] Styles
-    - [x] .css
-    - [x] Bundling
-  - [x] PDFs
-  - [x] Videos
-  - [x] Arbitrary data
-- [x] Add homepage to global nav
-- [x] Page lists
-- [x] Dates
-- [x] robots.txt
-- [x] sitemap.xml
-- [x] 404.html
-- [ ] Better URL normalization (see notes)
-- [x] Name casing
-- [x] TUI
-  - [x] Create settings.md
-    - [x] Site title
-    - [ ] Webmentions
-    - [x] Logo
-    - [x] Wordmark
-    - [ ] Identity (rel=me)
-    - [x] Filename breadcrumbs
-    - [x] RSS
-    - [x] Sitemap
-  - [x] Create home.md
-  - [ ] Create folder settings files
-    - [ ] Title
-    - [ ] Breadcrumb
-- [ ] Remove index file rules
-- [x] Custom CSS
-  - [x] styles.css
-  - [ ] Any CSS file
-- [x] Tags
-- [ ] Date format settings
-- [ ] ::mark::
-- [x] Infer images
-- [ ] Favicon
-- [-] Webmentions
-- [x] HTML boilerplate
-- [ ] View transitions
-- [x] Logo
-- [x] Wordmark
-- [ ] Sort nav items
-- [ ] Canonical URL
-- [ ] Handle external links
-- [x] Admonitions
-- [ ] Use hgroup for site title, page title, etc
-- [x] Images as `<figure>`
-- [ ] Hidden routes
-- [ ] Frontmatter settings
-  - [ ] HTML
-  - [ ] RSS
-  - [ ] Sitemap
-- [x] Heading anchors
-- [ ] Taxonomy pages and smart frontmatter
-- [x] CSS cache busting
-- [x] Slogan in homepage title
-- [ ] GFM emojis (:smile:)
-
-### Medium priority
-
-- [ ] Tests
-- [ ] Internal backlinks
-- [ ] Break code into multiple files
-- [ ] 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
-- [x] Better signals
-  - [x] File-written callback
-- [ ] Themes
-- [ ] Deploy
-  - [ ] Cloudflare pages
-  - [ ] GitHub pages
-- [-] Post-publish work (ping webmentions)
-- [ ] [Desktop app](https://blackboard.sh/electrobun/docs/)
-- [ ] Mermaid
-- [ ] Codeblock syntax highlighting
-- [ ] Extraction utilities (regex in archive)
-- [ ] Smarter frontmatter
-  - [ ] Object dl
-  - [ ] Array ul
-  - [ ] Image
-  - [ ] URL
-  - [ ] Date
-- [x] TOC
-- [ ] Versioning/publishing script
-- [ ] Verify all element types from Obsidian
-- [ ] Order/position/kanban
-- [ ] Next/prev links
-- [ ] Banner
-- [ ] CTA
-- [ ] Menu toggle
-- [ ] Icons sets
-- [ ] Auto-icons (:fa-rocket:)
-- [ ] Frontmatter icons
-
-### Low priority
-
-- [ ] Footnotes
-- [ ] Frontmatter taxonomies
-- [ ] Recursive frontmatter
-- [ ] Browser search
-- [ ] Pagination
-- [ ] Dialogue/spoiler alert
-- [ ] Copy code button
-- [ ] Tabbed element
-- [ ] Multi-lingual
-- [ ] Routing rules (see notes)
-- [ ] ATProto
-  - [ ] Liking
-  - [ ] Commenting
-- [ ] More inferred properties
-  - [ ] Email
-  - [ ] Phone number
-  - [ ] Location
-  - [ ] Color
-  - [ ] Price
-  - [ ] ISBN
-- Contact form
-- Subscription form
-- Faceted search
-
-## Notes and questions
-
-rel=author? rel=bookmark? rel=external?
-
-
-Annotations (see notes)
-
-Interactivity (see notes)
-
-Calculated properties?
-
-
-OG tags to consider:
+Vowel turns a folder of markdown files into a website. Write pages as
+plain `.md` files, in Obsidian or any editor; Vowel works out titles,
+dates, breadcrumbs, menus, tags, a feed and a sitemap from the files
+and how they're arranged, so there's almost nothing to configure.
 
+**Documentation: [vowel.cc](https://vowel.cc)**
+
+## Start
+
+Vowel needs [Node.js](https://nodejs.org) 26 or later. In the folder
+that holds your markdown:
+
+```bash
+npx vowel@latest
 ```
-  
-  /*
-    og:type - The type of your object, e.g., "video.movie". Depending on the type you specify, other properties may also be required.
-    og:locale - The locale these tags are marked up in. Of the format language_TERRITORY. Default is en_US.
-    article:published_time - datetime - When the article was first published.
-    article:modified_time - datetime - When the article was last changed.
-    article:expiration_time - datetime - When the article is out of date after.
-    article:author - profile array - Writers of the article.
-    article:section - string - A high-level section name. E.g. Technology
-    article:tag - string array - Tag words associated with this article.
-  */
+
+The first time, a short setup offers to write a `settings.md` and a
+`home.md`. Vowel then builds the site and serves a preview at
+`http://localhost:8000`, updating it as you edit.
+
+## Publish
+
+```bash
+vowel export ../my-site          # build into a folder, to upload anywhere
+vowel --command deploy           # build and deploy to Cloudflare Pages
 ```
+
+See [the docs](https://vowel.cc) for deploying, AT Protocol publishing,
+themes, and every setting.
+
+## How it's built
+
+Vowel is a set of plugins for [Votive](https://github.com/samlfair/votive),
+a file processor that turns sources into targets and rebuilds only what
+an edit changed.
+
+## Contributing
+
+Run the tests with `node --test tests/*.js`. Plans and open questions
+are in [ROADMAP.md](./ROADMAP.md).
+
+## License
+
+[MIT](./LICENSE)

package/bin.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import fs from "node:fs/promises"
-import { intro, note, text, select, confirm, spinner, outro, box } from "@clack/prompts"
+import os from "node:os"
+import path from "node:path"
+import { intro, note, text, select, confirm, spinner, outro, box, isCancel, cancel } from "@clack/prompts"
 import { parse } from "@bomb.sh/args"
 import t from "@bomb.sh/tab"
 import votive from "votive"
@@ -19,7 +21,23 @@ function wait(ms) {
 }
 
 import init from "./index.js"
-import { shouldClear } from "./cli.js"
+import { shouldClear, normalizeDomain, wrongFolderWarning } from "./cli.js"
+
+/**
+ * A prompt's answer - or, when the author pressed Ctrl-C or Escape, a
+ * clean exit. clack returns a cancel symbol instead of an answer, and
+ * the wizard used to carry on with it until a template string threw
+ * "Cannot convert a Symbol value to a string". Nothing has been written
+ * at that point: the wizard writes its files last.
+ * @template T
+ * @param {T | symbol} value
+ * @returns {T}
+ */
+function answer(value) {
+  if (!isCancel(value)) return /** @type {T} */ (value)
+  cancel("Setup cancelled. Nothing was written.")
+  process.exit(0)
+}
 
 /**
  * Discards the build database. Only under --clear (alias --reset): an
@@ -38,6 +56,22 @@ async function removeDatabase(verbose) {
   }
 }
 
+/**
+ * Empties the buffer cache: an image's measurements and derivative list,
+ * cached by votive so a warm start doesn't decode it again. Without
+ * this, a reset still reused every image's old read. Only the `.json`
+ * results go. The `cache-key` file stays, because votive empties a
+ * folder that has no key, so removing it would discard the next
+ * launch's fresh cache. URL fetches are not cached here.
+ * @param {boolean} verbose
+ */
+async function removeBufferCache(verbose) {
+  const entries = await fs.readdir(config.cacheDirectory).catch(() => [])
+  const results = entries.filter(name => name.endsWith(".json"))
+  await Promise.all(results.map(name => fs.rm(path.join(config.cacheDirectory, name), { force: true })))
+  if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", results.length ? "buffer cache cleared" : "no buffer cache found")}`)
+}
+
 /** @param {boolean} verbose */
 async function removeOutput(verbose) {
   try {
@@ -64,14 +98,14 @@ async function wizard() {
   {
     box(`Welcome!\n\nVowel is a static blog generator. It bundles markdown into HTML.`)
 
-    await select({
+    answer(await select({
       message: "Proceed",
       options: [
         {
           value: true,
           label: "OK"
         }]
-    })
+    }))
 
     box(`Vowel infers most relevant information from common markdown conventions, so it requires very little configuration.
 
@@ -80,25 +114,25 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 
 
 
-    const proceed = await confirm({
+    const proceed = answer(await confirm({
       message: "Generate settings file"
-    })
+    }))
 
     if (proceed) {
       const frontmatter = [`---`]
 
       box(`Change these configurations by editing 'settings.md'.`)
 
-      const websiteName = await text({
+      const websiteName = answer(await text({
         message: "Website name",
         placeholder: "My Cool Website"
-      })
+      }))
 
       frontmatter.push(`name: ${websiteName}`)
 
       box(`Vowel comes loaded with themes. You can override these themes by writing styles in a 'styles.css' file at the root of your project.`)
 
-      const theme = await select({
+      const theme = answer(await select({
         message: "Theme",
         options: [
           {
@@ -122,7 +156,7 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
             hint: 'write your own styles in `./styles.css`'
           }
         ]
-      })
+      }))
 
       if (theme) {
         frontmatter.push(`theme: ${theme}`)
@@ -130,21 +164,24 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 
       box(`To publish a sitemap and RSS feed, provide the domain that you plan to use.`)
 
-      const domain = await text({
+      const domain = answer(await text({
         message: "Domain",
         placeholder: "thebomb.com"
-      })
+      }))
 
-      if (domain) {
-        frontmatter.push(`domain: ${domain}`)
+      // As pasted from a browser: https://Example.com/ is example.com.
+      const siteDomain = normalizeDomain(domain)
+
+      if (siteDomain) {
+        frontmatter.push(`domain: ${siteDomain}`)
       }
 
       box(`To credit an author on your RSS feed, provide an author.`)
 
-      const author = await text({
+      const author = answer(await text({
         message: "Author",
         placeholder: "George Constanza"
-      })
+      }))
 
       if (author) {
         frontmatter.push(`author: ${author}`)
@@ -152,15 +189,16 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 
       box(`Markdown files are pages. Filenames are breadcrumbs. Folders are website sections. 'home.md' is your homepage.`)
 
-      const homepage = await confirm({
+      const homepage = answer(await confirm({
         message: "Generate homepage"
-      })
+      }))
 
-      // A tagline is a page's; the homepage's is the site's hero.
-      const tagline = await text({
-        message: "Homepage tagline (leave empty to skip)",
+      // A slogan is a page's; the homepage's is the site's hero. Only
+      // asked for the homepage the wizard is about to write.
+      const slogan = homepage ? answer(await text({
+        message: "Homepage slogan (leave empty to skip)",
         placeholder: "All the news that's fit to blog"
-      })
+      })) : undefined
 
       const spin = spinner()
 
@@ -178,14 +216,14 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
 
       const homeExists = await exists("home.md")
 
-      if (!homeExists) {
-        const homeFrontmatter = tagline ? `---\ntagline: ${tagline}\n---\n` : ""
+      if (homepage && !homeExists) {
+        const homeFrontmatter = slogan ? `---\nslogan: ${slogan}\n---\n` : ""
         await fs.writeFile("home.md", `${homeFrontmatter}# Home\n\nWelcome home!`, "utf-8")
       }
 
       spin.clear()
 
-      await select({
+      answer(await select({
         message: "Ready to go. Vowel will now launch your website.",
         options: [
           {
@@ -193,7 +231,7 @@ The few configurations that Vowel uses live in a 'settings.md' file at the root
             label: "Let's go"
           }
         ]
-      })
+      }))
 
 
     }
@@ -243,18 +281,40 @@ async function main() {
     return
   }
 
-  const dbExists = await exists(config.databasePath)
+  // `vowel export <folder>`: the export command (plugins/export), spelled
+  // as a word rather than --command/--payload.
+  if (args._?.[0] === "export") {
+    await runCLICommand("export", JSON.stringify({ path: args._[1] }))
+    return
+  }
+
+  // A site is a folder with a settings.md; the wizard writes one. Not "no
+  // database yet", which was also true of every site cloned onto a new
+  // machine. And only with a terminal to ask in: under CI or a pipe the
+  // prompts waited forever.
+  const settingsExists = await exists("settings.md")
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+  if (!settingsExists && interactive) {
+    const entries = await fs.readdir(".")
+    const folder = process.cwd()
+    const warning = wrongFolderWarning(entries, { folder, home: folder === os.homedir() })
+    if (warning && !answer(await confirm({ message: warning, initialValue: false }))) {
+      cancel("Run vowel inside your site's folder, or in a new, empty one.")
+      return
+    }
+  }
 
   if (shouldClear(args)) {
     await removeDatabase(args.logging === "verbose")
+    await removeBufferCache(args.logging === "verbose")
     await removeOutput(args.logging === "verbose")
   }
   await fs.mkdir(config.targetFolder, { recursive: true })
 
-  // The wizard runs on a first launch only: no database yet is the one
-  // signal that legitimately means "new project", and --clear does not
-  // change that - a cleared project is still one that was set up.
-  if (!args.skip && !dbExists) {
+  // The wizard runs for a new site only; --clear doesn't change that - a
+  // cleared project is still one that was set up.
+  if (!args.skip && !settingsExists && interactive) {
     // const loading = votive({ ...config, verbose: false })
     await wizard()
     // await (loading)

package/cli.js

@@ -13,3 +13,35 @@
 export function shouldClear(args) {
   return Boolean(args?.clear || args?.reset)
 }
+
+/**
+ * A domain as settings.md wants it: `https://Example.com/` → `example.com`.
+ * What the wizard's prompt gets is whatever someone pasted from a browser.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeDomain(value) {
+  if (typeof value !== "string") return ""
+  return value.trim().replace(/^[a-z]+:\/\//i, "").replace(/\/+$/, "").toLowerCase()
+}
+
+/**
+ * Whether this looks like the wrong folder to make a site in, and why,
+ * as the question to ask - or undefined when it looks fine. Vowel makes
+ * a site from everything in the folder it runs in, so starting it in a
+ * home folder, or a folder of other things, sets up and scans all of
+ * it. A new, empty folder is fine; so is one with markdown in it.
+ * Only asked when there is no settings.md: a folder that has one is a
+ * site already.
+ * @param {string[]} entries - the folder's own entries, by name
+ * @param {{ folder: string, home: boolean }} where
+ * @returns {string | undefined}
+ */
+export function wrongFolderWarning(entries, { folder, home }) {
+  const visible = entries.filter(name => !name.startsWith("."))
+  const markdown = visible.filter(name => name.toLowerCase().endsWith(".md"))
+  if (home) return `${folder} is your home folder. Vowel makes a website from everything in the folder it runs in. Set up a site here anyway?`
+  if (markdown.length || !visible.length) return undefined
+  const others = visible.length === 1 ? "1 other thing" : `${visible.length} other things`
+  return `${folder} has no markdown files, and ${others} in it. Vowel makes a website from everything in the folder it runs in. Set up a site here anyway?`
+}

package/config.js

@@ -1,4 +1,5 @@
 import path from "node:path"
+import { readFileSync } from "node:fs"
 import { resolveProjectFolder } from "votive"
 import { systemDirectoryFor } from "./systemPaths.js"
 import { secretRouter } from "./secretPaths.js"
@@ -16,6 +17,7 @@ import vowelAtprotoPlugin from "./plugins/atproto/index.js"
 import vowelPublishPlugin from "./plugins/publish/index.js"
 import vowelURLsPlugin from "./plugins/urls/index.js"
 import vowelSecretPagesPlugin from "./plugins/secret-pages/index.js"
+import vowelExportPlugin from "./plugins/export/index.js"
 
 /** @import {VotiveConfig} from "votive" */
 
@@ -29,6 +31,14 @@ import vowelSecretPagesPlugin from "./plugins/secret-pages/index.js"
  * the values), and a hex digest is lowercase already.
  * @param {string} sourcePath
  */
+/**
+ * Vowel's part of the cache key (votive's cacheKey.js): a warm start
+ * reuses the build cache only if this same version of vowel made it, so
+ * an upgrade that changes a bundled stylesheet or how pages render is
+ * seen without a `--clear`.
+ */
+const VOWEL_VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version
+
 function vowelRouter(sourcePath) {
   return secretRouter(sourcePath).toLowerCase()
 }
@@ -43,6 +53,7 @@ const defaultPlugins = [
   vowelFontsPlugin,
   vowelAssetsPlugin,
   vowelDeployCloudflarePlugin,
+  vowelExportPlugin,
   vowelURLsPlugin,
   vowelAtprotoPlugin,
   vowelPublishPlugin,
@@ -103,6 +114,7 @@ function createConfig(sourceFolder = ".", overrides = {}) {
     databasePath: path.join(systemDirectory, ".votive.db"),
     cacheDirectory: path.join(systemDirectory, ".cache"),
     plugins: [...defaultPlugins, ...(extraPlugins ?? [])],
+    cacheKey: `vowel@${VOWEL_VERSION}`,
     ...rest
   }
 }

package/extractDate.js

@@ -143,5 +143,5 @@ function extractDate(text) {
 }
 
 export default extractDate
-export { extractDate, dateSpan }
+export { extractDate, dateSpan, monthIndex }