mothwing 0.0.2 → 0.0.4

package/README.md

@@ -1,5 +1,5 @@
 # mothwing
-A small static site builder for pages as light as a moth's wing. Plain HTML in, plain HTML out, with hashed asset links and modulepreloads for code split JS. The rest is there when you ask for it: SEO tags, a Content-Security-Policy that allows only your own inline scripts, sitemaps dated from git, robots.txt and minified HTML.
+**Build, don't re-learn.** A small static site builder for pages as light as a moth's wing. Plain HTML in, plain HTML out, with hashed asset links and modulepreloads for code split JS. The rest is there when you ask for it: SEO tags, a Content-Security-Policy that allows only your own inline scripts, sitemaps dated from git, robots.txt and minified HTML.
 
 It was born as the build script of [ffxiv.watch](https://ffxiv.watch), and got tweaked over time until I was a little too proud of it to keep it there. So it branched out into its own thing, for any site that wants the same.
 
@@ -60,6 +60,20 @@ export default () => ({ year: new Date().getFullYear() })
 <footer>{{ site.year }}</footer>  <!-- into objects with dots -->
 ```
 
+An attribute that's a placeholder and nothing else follows its value: `false` or `null` leaves it out, and `true` makes it a bare attribute.
+
+```html
+<option value="{{ group.slug }}" selected="{{ group.selected }}">  <!-- selected, or nothing -->
+<section hidden="{{ events.none }}">                               <!-- hidden, or nothing -->
+```
+
+A `.js` file can also say what it reads, relative to `src/`. The pages using it are dated by those files in the sitemap, and render again in dev when they change:
+
+```js
+// src/data/events.js
+export const sources = ["js/data/lodestone.json"]
+```
+
 ## Loops
 ```html
 <ul>
@@ -81,7 +95,7 @@ Every tag is ordinary HTML to an editor or formatter. Templates formatted by Pre
 ## Pages
 `src/pages/about.html` is `/about/`, `src/pages/blog/index.html` is `/blog/`.
 
-`[projects.id].html` makes a page per item of `projects` in the data folder, with its `id` as the URL: `src/pages/projects/[projects.id].html` is `/projects/hexclock/` for `{ "id": "hexclock" }`. The item is `{{ page }}`, and the list links to the pages by the same field, `/projects/{{ project.id }}/`.
+`[projects.id].html` makes a page per item of `projects` in the data folder, with its `id` as the URL: `src/pages/projects/[projects.id].html` is `/projects/hexclock/` for `{ "id": "hexclock" }`. An id that's fine in a URL is kept as it is, `create_ssh_key` included, anything else is made into one: `Hex Clock` is `hex-clock`. The item is `{{ page }}`, and the list links to the pages by the same field, `/projects/{{ project.id }}/`. An item with a `sources` list is dated by those files instead of the whole data file, so editing one item doesn't date every page.
 
 ### .data.js
 For values that take more than the data folder, a page can have a `.data.js` next to it, whose default export returns them. Its values come before the data folder's:
@@ -137,7 +151,7 @@ Off until you turn them on. `true` turns one on as it comes, an object changes h
 | --- | --- | --- |
 | `minify` | Minifies the HTML of production builds | html-minifier-terser options |
 | `csp` | A `<meta>` Content-Security-Policy: only your own files, and your inline scripts by their hash | Directives over the defaults, `{ "style-src": "'self' 'unsafe-inline'" }` |
-| `sitemap` | `sitemap.xml`, each page dated by the last commit to its files | `sections` that get a sitemap each, `dates: false` to leave git out |
+| `sitemap` | `sitemap.xml` with every page, each dated by the last commit to its files | `sections` that get a sitemap each, behind a sitemap index, for big sites. `dates: false` to leave git out |
 | `robots` | `robots.txt` that allows everything, pointing at the sitemap | `block` crawlers by name, `disallow` paths |
 | `cname` | `CNAME` with the domain, for GitHub Pages | |
 | `activeLinks` | `aria-current="page"` on links to the page they're on, `"true"` on links to its section | A function `(href, route)` returning `"page"`, `"section"` or `false`, `undefined` keeps the default |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mothwing",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A small static site builder for pages as light as a moth's wing",
   "keywords": [
     "static-site-generator",

package/src/build.js

@@ -51,12 +51,15 @@ export async function buildHTML(site, state, { hashed = true, only } = {}) {
     for (const [file, content] of Object.entries(route.props.files ?? {})) writeIfChanged(path.join(site.out, file), content)
   }
 
-  // A page that used the data folder is dated by it too
+  // A page that used the data folder is dated by it too, and by what its files say they're made from
   for (const route of routes) {
     if (route.props.page) continue
     for (const name of state.used.get(route.source) ?? []) {
       const file = state.data.files[name]
-      if (file && !(name in route.props) && !route.sources.includes(file)) route.sources.push(file)
+      if (!file || name in route.props) continue
+      for (const source of [file, ...state.data.sources[name] ?? []]) {
+        if (!route.sources.includes(source)) route.sources.push(source)
+      }
     }
   }
   log("HTML", `Done rendering ${routes.length} pages${written < routes.length ? `, ${written} changed` : ""}`)

package/src/config.js

@@ -55,7 +55,8 @@ export const CONFIG_FILE = "mothwing.config.js"
 
 /**
  * @typedef {object} SitemapConfig
- * @property {string[]} [sections] Sections that get a sitemap of their own, the rest share sitemap-pages.xml
+ * @property {string[]} [sections] Sections that get a sitemap of their own behind a sitemap index, the rest share
+ *   sitemap-pages.xml. Without any, sitemap.xml has every page itself
  * @property {boolean} [dates] Date each page by the last git commit to its files. true
  */
 

package/src/data.js

@@ -8,34 +8,51 @@ import { posix } from "./log.js"
  * @typedef {object} SiteData
  * @property {Record<string, any>} values projects.json -> values.projects, a folder is an object of its files
  * @property {Record<string, string>} files Each top level name -> its file or folder, relative to src
+ * @property {Record<string, string[]>} sources Each top level name -> what its JS files say they're made from, see read
  */
 
 /**
  * @param {string} file
- * @returns {Promise<any>} A JSON file as it is, a JS file's default export, called first when it's a function
+ * @returns {Promise<{ value: any, sources: string[] }>} A JSON file as it is, a JS file's default export, called first
+ *   when it's a function. A JS file can also `export const sources`, the files it reads (relative to src), so the pages
+ *   using it are dated by them too, and render again in dev when they change
  */
 async function read(file) {
-  if (file.endsWith(".json")) return JSON.parse(fs.readFileSync(file, "utf8"))
-  const value = (await import(pathToFileURL(file).href)).default
-  return typeof value === "function" ? await value() : value
+  if (file.endsWith(".json")) return { value: JSON.parse(fs.readFileSync(file, "utf8")), sources: [] }
+  const module = await import(pathToFileURL(file).href)
+  const value = typeof module.default === "function" ? await module.default() : module.default
+  return { value, sources: Array.isArray(module.sources) ? module.sources : [] }
 }
 
 /**
  * @param {string} dir
  * @param {string} from For errors, the folder relative to src
- * @returns {Promise<Record<string, any>>}
+ * @param {(name: string, file: string, value: any, sources: string[]) => void} add Gets each file and folder in it
  */
-async function readFolder(dir, from) {
-  /** @type {Record<string, any>} */
-  const values = {}
+async function readEach(dir, from, add) {
+  const seen = new Set()
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const file = path.join(dir, entry.name)
     const name = entry.isDirectory() ? entry.name : entry.name.replace(/\.(json|js)$/, "")
     if (!entry.isDirectory() && name === entry.name) continue
-    if (name in values) throw new Error(`${from}/${entry.name}: there's more than one ${name} in ${from}`)
-    values[name] = entry.isDirectory() ? await readFolder(file, `${from}/${entry.name}`) : await read(file)
+    if (seen.has(name)) throw new Error(`${from}/${entry.name}: there's more than one ${name} in ${from}`)
+    seen.add(name)
+
+    if (entry.isDirectory()) {
+      /** @type {Record<string, any>} */
+      const values = {}
+      /** @type {string[]} */
+      const sources = []
+      await readEach(file, `${from}/${entry.name}`, (inner, _, value, own) => {
+        values[inner] = value
+        sources.push(...own)
+      })
+      add(name, file, values, sources)
+    } else {
+      const { value, sources } = await read(file)
+      add(name, file, value, sources)
+    }
   }
-  return values
 }
 
 /**
@@ -44,11 +61,14 @@ async function readFolder(dir, from) {
  */
 export async function loadData(site) {
   const dir = path.join(site.src, site.data)
-  if (!fs.existsSync(dir)) return { values: {}, files: {} }
+  /** @type {SiteData} */
+  const data = { values: {}, files: {}, sources: {} }
+  if (!fs.existsSync(dir)) return data
 
-  const values = await readFolder(dir, site.data)
-  const files = Object.fromEntries(fs.readdirSync(dir, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() || /\.(json|js)$/.test(entry.name))
-    .map(entry => [entry.isDirectory() ? entry.name : entry.name.replace(/\.(json|js)$/, ""), posix(path.join(site.data, entry.name))]))
-  return { values, files }
+  await readEach(dir, site.data, (name, file, value, sources) => {
+    data.values[name] = value
+    data.files[name] = posix(path.relative(site.src, file))
+    data.sources[name] = [...new Set(sources)]
+  })
+  return data
 }

package/src/deps.js

@@ -55,10 +55,13 @@ export async function dependencies(site, state, routes) {
     const dataFile = `${pagesDir}/${source.replace(/\.html$/, ".data.js")}`
     if (fs.existsSync(path.join(site.src, dataFile))) (await importsCached(dataFile)).forEach(file => files.add(file))
 
-    for (const name of state.used.get(source) ?? []) {
+    // The data it used, and for a [projects.id].html page the list it's made from
+    const fromData = source.match(/\[([\w.]+)\.\w+\]\.html$/)?.[1].split(".")[0]
+    for (const name of new Set([...state.used.get(source) ?? [], ...fromData ? [fromData] : []])) {
       const file = state.data.files[name]
       if (!file) continue
       files.add(file)
+      state.data.sources[name]?.forEach(input => files.add(input))
       if (file.endsWith(".js")) (await importsCached(file)).forEach(input => files.add(input))
     }
     deps[source] = [...files]

package/src/render.js

@@ -31,7 +31,7 @@ import { includeHtml, parseAttrs, parseTemplate, renderNodes } from "./template.
 
 /** @returns {BuildState} */
 export const buildState = () => ({
-  data: { values: {}, files: {} },
+  data: { values: {}, files: {}, sources: {} },
   assetUrls: new Map(),
   templates: new Map(),
   used: new Map(),

package/src/routes.js

@@ -110,16 +110,21 @@ function pagesFromData(site, siteData, source, list, key) {
   const from = posix(path.relative(site.src, path.join(site.pages, source)))
   const items = lookup(siteData.values, list)
   if (!Array.isArray(items)) throw new Error(`${from}: ${site.data} has no list called ${list}`)
-  const dataFile = siteData.files[list.split(".")[0]]
+  const top = list.split(".")[0]
+  const dataSources = [siteData.files[top], ...siteData.sources[top] ?? []]
 
   const seen = new Set()
   return items.map((item, i) => {
     if (item?.[key] === undefined) throw new Error(`${from}: item ${i} of ${list} has no ${key}`)
-    const pageSlug = slug(String(item[key]))
+    // A value that's fine in a URL already is kept as it is, so existing links like /docs/create_ssh_key/ keep working
+    const value = String(item[key])
+    const pageSlug = /^[\w.-]+$/.test(value) ? value : slug(value)
     if (seen.has(pageSlug)) throw new Error(`${from}: two of ${list} are both "${pageSlug}"`)
     seen.add(pageSlug)
     const output = source.replace(/\[[\w.]+\]\.html$/, `${pageSlug}/index.html`)
-    // Dated by its data alone, a template tweak would otherwise date every page at once
-    return { source, output, url: outputUrl(output), props: { page: item }, sources: [dataFile] }
+    // Dated by its data alone, a template tweak would otherwise date every page at once. An item can say which of the
+    // data it's made from, so a change to one doesn't date them all
+    const sources = Array.isArray(item.sources) && item.sources.length ? item.sources : dataSources
+    return { source, output, url: outputUrl(output), props: { page: item }, sources }
   })
 }

package/src/seo.js

@@ -35,8 +35,8 @@ export function seoTags(site, route, attrs) {
   const pageDescription = attr("description")
   if (!pageTitle || !pageDescription) throw new Error(`${route.source}: <x-seo> needs a title and a description`)
   const description = fitDescription(pageDescription, maxDescription)
-  // The front page keeps it, for people searching for the site by its name
-  const named = `${pageTitle} - ${siteName}`
+  // The front page keeps it, for people searching for the site by its name, unless it's the site's name already
+  const named = unescapeHtml(pageTitle) === siteName ? pageTitle : `${pageTitle} - ${siteName}`
   const title = route.url === "/" || unescapeHtml(named).length <= maxTitle ? named : pageTitle
 
   const url = `${site.url}${route.url}`

package/src/site.js

@@ -34,7 +34,8 @@ function lastModified(site, cache, files) {
  * @param {boolean} [dated] Add each page's lastmod, from git, which takes a moment
  */
 export async function writeSiteFiles(site, routes, dated = true) {
-  const files = [site.cname && "CNAME", site.sitemap && "the sitemaps", site.robots && "robots.txt"].filter(Boolean)
+  const sitemapFiles = site.sitemap && (site.sitemap.sections.length ? "the sitemaps" : "the sitemap")
+  const files = [site.cname && "CNAME", sitemapFiles, site.robots && "robots.txt"].filter(Boolean)
   if (!files.length) return
   log("SITE", `Writing ${files.length > 1 ? `${files.slice(0, -1).join(", ")} and ${files.at(-1)}` : files[0]}`)
 
@@ -45,7 +46,7 @@ export async function writeSiteFiles(site, routes, dated = true) {
   const sitemaps = new Map()
   if (site.sitemap) {
     const cache = new Map()
-    // A sitemap per section behind a sitemap index, so Search Console shows how each one is indexed on its own
+    // With sections, a sitemap per section behind a sitemap index, so Search Console shows how each one is indexed on its own
     for (const route of routes.filter(route => route.source !== site.notFound)) {
       const section = route.url.split("/")[1]
       const name = site.sitemap.sections.includes(section) ? section : "pages"
@@ -72,15 +73,23 @@ export async function writeSiteFiles(site, routes, dated = true) {
      */
     const entry = (tag, loc, lastmod) => `  <${tag}><loc>${loc}</loc>${lastmod ? `<lastmod>${lastmod}</lastmod>` : ""}</${tag}>`
 
-    const index = []
-    for (const [name, pages] of sitemaps) {
-      const file = `sitemap-${name}.xml`
-      fs.writeFileSync(path.join(site.out, file), xml("urlset", pages.map(p => entry("url", `${site.url}${p.url}`, p.lastmod))))
-      // YYYY-MM-DD sorts as text, so the newest is the last
-      const newest = pages.map(p => p.lastmod).filter(Boolean).sort().at(-1)
-      index.push(entry("sitemap", `${site.url}/${file}`, newest))
+    /** @param {{ url: string, lastmod: string | null | false }[]} pages */
+    const urlset = (pages) => xml("urlset", pages.map(p => entry("url", `${site.url}${p.url}`, p.lastmod)))
+
+    // Without sections, it's one sitemap.xml with every page, all a small site needs
+    if (!site.sitemap.sections.length) {
+      fs.writeFileSync(path.join(site.out, "sitemap.xml"), urlset(sitemaps.get("pages") ?? []))
+    } else {
+      const index = []
+      for (const [name, pages] of sitemaps) {
+        const file = `sitemap-${name}.xml`
+        fs.writeFileSync(path.join(site.out, file), urlset(pages))
+        // YYYY-MM-DD sorts as text, so the newest is the last
+        const newest = pages.map(p => p.lastmod).filter(Boolean).sort().at(-1)
+        index.push(entry("sitemap", `${site.url}/${file}`, newest))
+      }
+      fs.writeFileSync(path.join(site.out, "sitemap.xml"), xml("sitemapindex", index))
     }
-    fs.writeFileSync(path.join(site.out, "sitemap.xml"), xml("sitemapindex", index))
   }
 
   if (site.robots) {

package/src/template.js

@@ -63,7 +63,8 @@ function find(values, name, context) {
 
 /**
  * {{ name }} is filled with the value as text, {{{ name }}} as HTML, on a line of its own each line indented like it.
- * Names can go into objects: {{ project.name }}.
+ * Names can go into objects: {{ project.name }}. An attribute that's one placeholder and nothing else follows its
+ * value: false or null leaves it out, true makes it a bare one, `selected="{{ group.selected }}"` -> `selected`.
  * @param {string} html
  * @param {Record<string, any>} values
  * @param {string} from For errors, the page's file
@@ -72,17 +73,22 @@ function find(values, name, context) {
  */
 export function fillPlaceholders(html, values, from, used = new Set()) {
   /** @param {string} name */
-  const value = (name) => {
-    const found = find(values, name, { from, used })
-    if (found === undefined) throw new Error(`${from}: nothing to fill {{ ${name} }} with`)
-    return String(found)
+  const found = (name) => {
+    const value = find(values, name, { from, used })
+    if (value === undefined) throw new Error(`${from}: nothing to fill {{ ${name} }} with`)
+    return value
   }
 
   // One pass, so what's filled in is never searched for placeholders itself
-  const placeholder = /^([ \t]*)\{\{\{\s*([\w.]+)\s*\}\}\}[ \t]*$|\{\{\{\s*([\w.]+)\s*\}\}\}|\{\{\s*([\w.]+)\s*\}\}/gm
-  return html.replace(placeholder, (_, indent, line, inline, text) => {
-    if (line) return value(line).split("\n").map(l => l.trim() ? indent + l : "").join("\n")
-    return inline ? value(inline) : escapeHtml(value(text))
+  const placeholder = /(\s+)([\w:-]+)="\{\{\s*([\w.]+)\s*\}\}"|^([ \t]*)\{\{\{\s*([\w.]+)\s*\}\}\}[ \t]*$|\{\{\{\s*([\w.]+)\s*\}\}\}|\{\{\s*([\w.]+)\s*\}\}/gm
+  return html.replace(placeholder, (_, space, attr, attrValue, indent, line, inline, text) => {
+    if (attr) {
+      const value = found(attrValue)
+      if (value === false || value === null) return ""
+      return value === true ? `${space}${attr}` : `${space}${attr}="${escapeHtml(String(value))}"`
+    }
+    if (line) return String(found(line)).split("\n").map(l => l.trim() ? indent + l : "").join("\n")
+    return inline ? String(found(inline)) : escapeHtml(String(found(text)))
   })
 }
 

package/types/config.d.ts

@@ -152,7 +152,8 @@ export type SeoConfig = {
 };
 export type SitemapConfig = {
     /**
-     * Sections that get a sitemap of their own, the rest share sitemap-pages.xml
+     * Sections that get a sitemap of their own behind a sitemap index, the rest share
+     * sitemap-pages.xml. Without any, sitemap.xml has every page itself
      */
     sections?: string[] | undefined;
     /**

package/types/data.d.ts

@@ -15,4 +15,8 @@ export type SiteData = {
      * Each top level name -> its file or folder, relative to src
      */
     files: Record<string, string>;
+    /**
+     * Each top level name -> what its JS files say they're made from, see read
+     */
+    sources: Record<string, string[]>;
 };

package/types/template.d.ts

@@ -11,7 +11,8 @@
 export function includeHtml(src: string, html: string, from: string, used?: Set<string>, depth?: number): string;
 /**
  * {{ name }} is filled with the value as text, {{{ name }}} as HTML, on a line of its own each line indented like it.
- * Names can go into objects: {{ project.name }}.
+ * Names can go into objects: {{ project.name }}. An attribute that's one placeholder and nothing else follows its
+ * value: false or null leaves it out, true makes it a bare one, `selected="{{ group.selected }}"` -> `selected`.
  * @param {string} html
  * @param {Record<string, any>} values
  * @param {string} from For errors, the page's file