kaloko 0.5.2 → 0.7.0

package/src/lib/docs-core.mjs

@@ -0,0 +1,450 @@
+// Living documentation (docs/DOCS-CHANGELOG.md, phases 2 and 3), the parts the CLI and the service share: where a
+// Markdown file sits in the docs (Diátaxis folders, sibling translations `guide.cs.md`), front matter, sections with
+// their step references, the guide as training steps, the translations report, stale sections, changelog items
+// without pictures, and a small Markdown renderer. No I/O and no Node built-ins: the worker imports this file too.
+import { findStepRefs, parseStepRef, parseChangelog, parseEntry } from './changelog-core.mjs'
+
+export const KINDS = ['tutorials', 'how-to', 'reference', 'explanation']
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/
+export const LANG = /^[a-z]{2}(-[A-Z]{2})?$/
+export const MAX_PAGE = 200 * 1024
+
+// ---------- files and paths ----------
+
+/**
+ * Where a file of the docs folder goes: `how-to/pay.md` → { path: 'how-to/pay', lang: null }, `how-to/pay.cs.md` →
+ * lang cs, `index.md` and `README.md` → the folder itself (`''`, `how-to`). Null for files that are not pages
+ * (not Markdown, hidden, or with a path the service does not take).
+ */
+export function docFile (rel) {
+  const p = String(rel || '').replace(/\\/g, '/').replace(/^\.?\//, '')
+  if (!/\.(md|markdown)$/i.test(p) || p.split('/').some((s) => !s || s.startsWith('.') || s.startsWith('_'))) return null
+  const parts = p.split('/')
+  let name = parts.pop().replace(/\.(md|markdown)$/i, '')
+  let lang = null
+  const m = name.match(/^(.+)\.([a-z]{2}(?:-[A-Z]{2})?)$/)
+  if (m) { name = m[1]; lang = m[2] }
+  if (/^(index|readme)$/i.test(name)) name = ''
+  const path = [...parts, name].filter(Boolean).join('/')
+  if (path && !path.split('/').every((s) => SEGMENT.test(s))) return null
+  if (path.length > 200) return null
+  return { path, lang }
+}
+
+/** Is this a page path the service stores ('' is the docs index)? */
+export const validDocPath = (p) => p === '' || (typeof p === 'string' && p.length <= 200 && p.split('/').every((s) => SEGMENT.test(s)))
+
+/** The Diátaxis kind of a page from its first folder (tutorials, how-to, reference, explanation), else null. */
+export function kindOf (path) {
+  const top = String(path || '').split('/')[0].toLowerCase()
+  const alias = { tutorial: 'tutorials', howto: 'how-to', 'how-tos': 'how-to', guides: 'how-to', explanations: 'explanation', concepts: 'explanation' }
+  const k = alias[top] || top
+  return KINDS.includes(k) ? k : null
+}
+
+// ---------- front matter ----------
+
+/** `---` front matter with a flat YAML subset (scalars, quoted strings, [a, b] lists, true/false, numbers). */
+export function frontMatter (md) {
+  const text = String(md || '').replace(/^/, '').replace(/\r/g, '')
+  const m = text.match(/^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/)
+  if (!m) return { data: {}, body: text }
+  const data = {}
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/)
+    if (!kv) continue
+    data[kv[1]] = scalar(kv[2].trim())
+  }
+  return { data, body: text.slice(m[0].length) }
+}
+function scalar (v) {
+  if (v === '') return ''
+  if (/^\[.*\]$/.test(v)) return v.slice(1, -1).split(',').map((x) => scalar(x.trim())).filter((x) => x !== '')
+  if (/^".*"$/.test(v) || /^'.*'$/.test(v)) return v.slice(1, -1)
+  if (v === 'true' || v === 'false') return v === 'true'
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+  return v.replace(/\s+#.*$/, '')
+}
+
+/** The title of a page: front matter title, else its first `# ` heading, else the last part of its path. */
+export function docTitle (md, path = '') {
+  const { data, body } = frontMatter(md)
+  if (typeof data.title === 'string' && data.title.trim()) return data.title.trim().slice(0, 200)
+  const h = body.match(/^#\s+(.+?)\s*#*\s*$/m)
+  if (h) return stripInline(h[1]).slice(0, 200)
+  const last = String(path || '').split('/').pop()
+  return last ? last.replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()) : 'Documentation'
+}
+
+/** The order of a page in the sidebar: front matter order / sidebar_position / nav_order, else null. */
+export const docOrder = (data) => [data?.order, data?.sidebar_position, data?.nav_order].find((x) => typeof x === 'number') ?? null
+
+const stripInline = (s) => String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*_]/g, '').trim()
+
+// ---------- sections ----------
+
+/** A heading id: lower case, accents dropped, words joined by dashes. */
+export function slugify (s) {
+  return String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'section'
+}
+
+/** Lines of a body with whether each is inside a fenced code block. */
+function fenced (lines) {
+  let inside = false
+  return lines.map((l) => { const fence = /^\s{0,3}(```|~~~)/.test(l); const was = inside; if (fence) inside = !inside; return was || fence })
+}
+
+/**
+ * The sections of a page body: text before the first heading (id '', level 0), then one per heading of level 1–3,
+ * each with its own text (up to the next heading of any of these levels) and its step references.
+ */
+export function sections (body) {
+  const lines = String(body || '').replace(/\r/g, '').split('\n')
+  const code = fenced(lines)
+  const out = []; const used = new Map()
+  let cur = { id: '', level: 0, title: '', lines: [] }
+  for (let i = 0; i < lines.length; i++) {
+    const h = !code[i] && lines[i].match(/^(#{1,3})\s+(.+?)\s*#*\s*$/)
+    if (h) {
+      out.push(cur)
+      let id = slugify(stripInline(h[2]))
+      const n = (used.get(id) || 0) + 1; used.set(id, n); if (n > 1) id = `${id}-${n}`
+      cur = { id, level: h[1].length, title: stripInline(h[2]), lines: [], heading: lines[i] }
+      continue
+    }
+    cur.lines.push(lines[i])
+  }
+  out.push(cur)
+  return out.filter((s) => s.level || s.lines.some((l) => l.trim())).map((s) => { const text = s.lines.join('\n'); return { id: s.id, level: s.level, title: s.title, text, refs: findStepRefs(text).filter((r) => r.parsed).map((r) => r.ref) } })
+}
+
+// ---------- training mode ----------
+
+/**
+ * A guide as training steps: every block (list item or paragraph) that shows a step becomes one step whose caption is
+ * the block's words and whose picture is its last step reference (the "after" of a before/after pair). A picture on
+ * its own line belongs to the text right above it. Returns [{ caption, ref, alt, refs }].
+ */
+export function trainingSteps (body) {
+  const blocks = []
+  const lines = String(body || '').replace(/\r/g, '').split('\n')
+  const code = fenced(lines)
+  let cur = null
+  const flush = () => { if (cur && cur.join('\n').trim()) blocks.push(cur.join('\n')); cur = null }
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i]
+    if (code[i]) { flush(); continue }
+    if (/^#{1,6}\s/.test(l)) { flush(); blocks.push({ heading: l.replace(/^#+\s+/, '').trim() }); continue }
+    if (/^\s{0,3}([-*+]|\d+[.)])\s+/.test(l)) { flush(); cur = [l.replace(/^\s{0,3}([-*+]|\d+[.)])\s+/, '')]; continue }
+    if (!l.trim()) { if (cur && i + 1 < lines.length && /^\s{2,}\S/.test(lines[i + 1])) { cur.push(''); continue } flush(); continue }
+    if (cur && /^\s+\S/.test(l)) { cur.push(l.trim()); continue }
+    if (!cur) cur = []
+    cur.push(l.trim())
+  }
+  flush()
+  const steps = []
+  let heading = null
+  let pendingText = null
+  for (const b of blocks) {
+    if (typeof b === 'object') { heading = b.heading; pendingText = null; continue }
+    const refs = findStepRefs(b).filter((r) => r.parsed)
+    const words = b.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/<!--[\s\S]*?-->/g, '').replace(/[ \t]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim()
+    if (!refs.length) { pendingText = words || null; continue }
+    const caption = words || pendingText || heading || refs[refs.length - 1].alt || ''
+    const last = refs[refs.length - 1]
+    steps.push({ caption, ref: last.ref, alt: last.alt, refs: refs.map((r) => r.ref), heading })
+    pendingText = null
+  }
+  return steps
+}
+
+// ---------- the sidebar ----------
+
+/**
+ * The sidebar of a set of pages (one language): the index first, then the Diátaxis folders in their order, then
+ * other folders; inside a folder by front matter order, then title. [{ path, title, kind, children: [...] }]
+ */
+export function buildNav (pages) {
+  const byPath = new Map(pages.map((p) => [p.path, p]))
+  const top = new Map()
+  for (const p of pages) {
+    if (p.path === '') continue
+    const [first] = p.path.split('/')
+    if (!top.has(first)) top.set(first, { path: first, title: byPath.get(first)?.title || folderTitle(first), kind: kindOf(first), order: byPath.get(first)?.order ?? null, page: byPath.has(first), children: [] })
+    if (p.path !== first) top.get(first).children.push({ path: p.path, title: p.title, kind: kindOf(p.path), order: p.order ?? null, page: true })
+  }
+  const rank = (n) => { const i = KINDS.indexOf(kindOf(n.path)); return i < 0 ? 10 : i }
+  const sort = (a, b) => (a.order ?? 1e9) - (b.order ?? 1e9) || String(a.title).localeCompare(String(b.title))
+  const list = [...top.values()].sort((a, b) => rank(a) - rank(b) || sort(a, b))
+  for (const n of list) n.children.sort(sort)
+  return [...(byPath.has('') ? [{ path: '', title: byPath.get('').title, kind: null, page: true, children: [] }] : []), ...list]
+}
+const FOLDERS = { tutorials: 'Tutorials', 'how-to': 'How-to guides', reference: 'Reference', explanation: 'Explanation' }
+export const folderTitle = (f) => FOLDERS[kindOf(f)] && kindOf(f) === f ? FOLDERS[f] : String(f).replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase())
+
+/** The nav flattened in reading order (for previous / next links). */
+export const navOrder = (nav) => nav.flatMap((n) => [...(n.page ? [n.path] : []), ...n.children.map((c) => c.path)])
+
+// ---------- translations ----------
+
+/**
+ * Which translations are missing or older than their original. `pages`: [{ path, lang (null = the original
+ * language), hash, front, updated (ISO, optional) }]; `languages`: the configured languages, the first is the
+ * original's. A translation is outdated when its front matter `source_hash` (a prefix of the original's SHA-256)
+ * differs from the original, or, without one, when the original changed later (git dates). Returns
+ * { languages, missing: [{ path, lang }], outdated: [{ path, lang, why }], orphans: [{ path, lang }] }.
+ */
+export function translationReport (pages, languages = []) {
+  const langs = [...new Set((languages || []).filter((l) => LANG.test(l)))]
+  const base = langs[0] || null
+  const others = langs.slice(1)
+  const originals = new Map(); const translations = new Map()
+  for (const p of pages) {
+    if (!p.lang || p.lang === base) originals.set(p.path, p)
+    else translations.set(`${p.path}|${p.lang}`, p)
+  }
+  const missing = []; const outdated = []; const orphans = []
+  for (const [path, o] of originals) {
+    for (const l of others) {
+      const t = translations.get(`${path}|${l}`)
+      if (!t) { missing.push({ path, lang: l }); continue }
+      const want = t.front?.source_hash ? String(t.front.source_hash) : null
+      if (want && o.hash && !o.hash.startsWith(want.toLowerCase())) outdated.push({ path, lang: l, why: 'source_hash' })
+      else if (!want && o.updated && t.updated && o.updated > t.updated) outdated.push({ path, lang: l, why: 'older' })
+    }
+  }
+  for (const t of translations.values()) if (!originals.has(t.path)) orphans.push({ path: t.path, lang: t.lang })
+  return { languages: langs, missing, outdated, orphans }
+}
+
+// ---------- stale sections ----------
+
+/**
+ * Sections whose pictures changed since the text was published. `recorded`: { ref: { hash, run } | null } taken when
+ * the page's text last changed; `current`: { ref: { hash, run, app_version, started_at } | null } now. A reference
+ * that had no picture then is not stale (it is new). Returns [{ section, title, refs: [{ ref, changed_in, run }] }].
+ */
+export function staleSections (body, recorded = {}, current = {}) {
+  const out = []
+  for (const s of sections(body)) {
+    const refs = []
+    for (const ref of new Set(s.refs)) {
+      const was = recorded?.[ref]; const now = current?.[ref]
+      if (!was?.hash || !now?.hash || was.hash === now.hash) continue
+      refs.push({ ref, changed_in: now.app_version || (now.started_at ? String(now.started_at).slice(0, 10) : null), run: now.run || null, was_run: was.run || null })
+    }
+    if (refs.length) out.push({ section: s.id, title: s.title, refs })
+  }
+  return out
+}
+
+// ---------- changelog items without pictures ----------
+
+const VISIBLE = ['Added', 'Changed', 'Removed']
+/**
+ * User-visible changelog items (Added, Changed, Removed) without a step reference, in Unreleased and the newest
+ * release. `<!-- no picture -->` in an item says it has nothing to show. [{ section, group, item }]
+ */
+export function itemsWithoutPictures (changelogText) {
+  const { sections: secs } = parseChangelog(changelogText)
+  const pick = [secs.find((s) => s.unreleased), secs.find((s) => !s.unreleased)].filter(Boolean)
+  const out = []
+  for (const s of pick) {
+    for (const g of parseEntry(s.body).groups) {
+      if (!VISIBLE.includes(g.name)) continue
+      for (const it of g.items) {
+        if (findStepRefs(it).some((r) => r.parsed) || /<!--\s*no[ -]picture\s*-->/i.test(it)) continue
+        out.push({ section: s.unreleased ? 'Unreleased' : s.version, group: g.name, item: it.split('\n')[0].replace(/<!--[\s\S]*?-->/g, '').trim().slice(0, 200) })
+      }
+    }
+  }
+  return out
+}
+
+// ---------- links between pages ----------
+
+/**
+ * Where a link in a page points: another page of the docs ({ path, hash }) for relative `.md` links (sibling
+ * translations included), else null (external links, anchors and anything else stay as written).
+ */
+export function docLink (fromPath, href, { isIndex = false } = {}) {
+  const h = String(href || '')
+  if (/^[a-z][a-z0-9+.-]*:|^\/\/|^#|^\//i.test(h)) return null
+  const [file, hash = ''] = h.split('#')
+  if (!/\.(md|markdown)$/i.test(file)) return null
+  const dir = isIndex ? String(fromPath || '').split('/').filter(Boolean) : String(fromPath || '').split('/').filter(Boolean).slice(0, -1)
+  for (const seg of file.split('/')) {
+    if (seg === '..') dir.pop()
+    else if (seg && seg !== '.') dir.push(seg)
+  }
+  const f = docFile(dir.join('/'))
+  return f ? { path: f.path, lang: f.lang, hash } : null
+}
+
+// ---------- Markdown to HTML ----------
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+export const escapeHtml = esc
+
+/** Inline Markdown: code, bold, italics, links (safe schemes; `link(href)` may rewrite or drop them). Images are removed. */
+export function inlineHtml (s, { link = null } = {}) {
+  let out = esc(String(s).replace(/!\[[^\]]*\]\([^)]*\)/g, ''))
+  const codes = []
+  out = out.replace(/`([^`]+)`/g, (_, c) => { codes.push(`<code>${c}</code>`); return `\u0000${codes.length - 1}\u0000` })
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>').replace(/__([^_]+)__/g, '<b>$1</b>').replace(/(^|[\s(])_([^_]+)_(?=$|[\s).,;:!?])/g, '$1<i>$2</i>').replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=$|[\s).,;:!?])/g, '$1<i>$2</i>')
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_, t, href) => {
+    const raw = href.replace(/&amp;/g, '&')
+    const target = link ? link(raw) : raw
+    if (target == null) return t
+    return /^(https?:\/\/|\/|#|mailto:|\.{0,2}\/?[A-Za-z0-9._/-]+(\.html)?(#[A-Za-z0-9_-]*)?$)/.test(target) && !/^javascript:/i.test(target) ? `<a href="${esc(target)}"${/^https?:/.test(target) ? ' rel="noopener"' : ''}>${t}</a>` : t
+  })
+  return out.replace(/\u0000(\d+)\u0000/g, (_, i) => codes[Number(i)])
+}
+
+const LIST = /^(\s{0,3})([-*+]|\d{1,9}[.)])\s+(.*)$/
+const IMG = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g
+
+/**
+ * Markdown to HTML for docs: headings (with ids), paragraphs, lists (nested by indentation), fenced code,
+ * blockquotes, tables, rules, inline formatting and pictures. `picture(images)` gets the images of one block
+ * ([{ alt, src, ref }]) and returns their HTML; `link(href)` rewrites links; `notice(sectionId)` adds HTML right
+ * under a section heading (stale notes); `headingIds` is filled with { level, id, title }. Raw HTML is escaped.
+ */
+export function renderMarkdown (body, opts = {}) {
+  const ids = opts.headingIds || []
+  const used = new Map()
+  const text = String(body || '').replace(/\r/g, '').replace(/<!--[\s\S]*?-->/g, '')
+  const html = blocks(text.split('\n'), { ...opts, ids, used, top: true })
+  return html
+}
+
+function picturesOf (text) {
+  const imgs = []
+  const words = String(text).replace(IMG, (_, alt, src) => { imgs.push({ alt, src, ref: parseStepRef(src) }); return ' ' })
+  return { imgs, words: words.replace(/[ \t]+\n/g, '\n').trim() }
+}
+
+function blocks (lines, o) {
+  const out = []
+  let i = 0
+  const para = []
+  const flush = () => {
+    if (!para.length) return
+    const { imgs, words } = picturesOf(para.join('\n'))
+    if (words) out.push(`<p>${inlineHtml(words.replace(/\n/g, ' '), o)}</p>`)
+    if (imgs.length) out.push(pics(imgs, o))
+    para.length = 0
+  }
+  while (i < lines.length) {
+    const l = lines[i]
+    const fence = l.match(/^\s{0,3}(```+|~~~+)\s*([\w-]*)/)
+    if (fence) {
+      flush()
+      const buf = []; i++
+      while (i < lines.length && !lines[i].trim().startsWith(fence[1])) buf.push(lines[i++])
+      i++
+      out.push(`<pre class="dc-code"><code${fence[2] ? ` class="language-${esc(fence[2])}"` : ''}>${esc(buf.join('\n'))}</code></pre>`)
+      continue
+    }
+    const h = l.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/)
+    if (h) {
+      flush()
+      const level = h[1].length
+      const title = h[2]
+      let id = slugify(stripInline(title))
+      const n = (o.used.get(id) || 0) + 1; o.used.set(id, n); if (n > 1) id = `${id}-${n}`
+      if (level <= 3) o.ids.push({ level, id, title: stripInline(title) })
+      const tag = `h${Math.min(6, level)}`
+      out.push(`<${tag} id="${esc(id)}">${inlineHtml(title, o)}${level > 1 && level <= 3 ? ` <a class="dc-anchor" href="#${esc(id)}" aria-hidden="true">#</a>` : ''}</${tag}>`)
+      if (level <= 3 && o.notice) { const x = o.notice(id); if (x) out.push(x) }
+      i++
+      continue
+    }
+    if (/^\s{0,3}([-*_])(\s*\1){2,}\s*$/.test(l)) { flush(); out.push('<hr>'); i++; continue }
+    if (/^\s{0,3}>/.test(l)) {
+      flush()
+      const buf = []
+      while (i < lines.length && /^\s{0,3}>/.test(lines[i])) buf.push(lines[i++].replace(/^\s{0,3}>\s?/, ''))
+      out.push(`<blockquote>${blocks(buf, { ...o, notice: null })}</blockquote>`)
+      continue
+    }
+    if (/^\s*\|.*\|\s*$/.test(l) && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(lines[i + 1])) {
+      flush()
+      const row = (x) => x.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim())
+      const head = row(l); i += 2
+      const rows = []
+      while (i < lines.length && /^\s*\|.*\|\s*$/.test(lines[i])) rows.push(row(lines[i++]))
+      out.push(`<div class="dc-table"><table><thead><tr>${head.map((c) => `<th>${inlineHtml(c, o)}</th>`).join('')}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${inlineHtml(c, o)}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`)
+      continue
+    }
+    const li = l.match(LIST)
+    if (li) {
+      flush()
+      const ordered = /\d/.test(li[2])
+      const start = ordered ? Number(li[2].replace(/\D/g, '')) : 1
+      const items = []
+      while (i < lines.length) {
+        const m = lines[i].match(LIST)
+        if (!m || /\d/.test(m[2]) !== ordered || m[1].length > 3) break
+        const indent = m[1].length + m[2].length + 1
+        const item = [m[3]]; i++
+        while (i < lines.length) {
+          const n = lines[i]
+          if (!n.trim()) {
+            // a blank line keeps the item open when indented text follows
+            if (i + 1 < lines.length && /^\s{2,}\S/.test(lines[i + 1])) { item.push(''); i++; continue }
+            break
+          }
+          if (LIST.test(n) && n.match(/^\s*/)[0].length < 2) break
+          if (/^\s{2,}/.test(n)) { item.push(n.replace(new RegExp(`^\\s{0,${Math.max(2, indent)}}`), '')); i++; continue }
+          if (/^(#{1,6}\s|\s{0,3}(```|~~~|>))/.test(n)) break
+          item.push(n.trim()); i++
+        }
+        items.push(item)
+        while (i < lines.length && !lines[i].trim() && i + 1 < lines.length && LIST.test(lines[i + 1]) && lines[i + 1].match(LIST)[1].length <= 3 && /\d/.test(lines[i + 1].match(LIST)[2]) === ordered) i++
+      }
+      const tag = ordered ? 'ol' : 'ul'
+      out.push(`<${tag}${ordered && start !== 1 ? ` start="${start}"` : ''}>${items.map((it) => `<li>${listItem(it, o)}</li>`).join('')}</${tag}>`)
+      continue
+    }
+    if (!l.trim()) { flush(); i++; continue }
+    para.push(l); i++
+  }
+  flush()
+  return out.join('\n')
+}
+
+/** A list item: its first paragraph inline (tight lists), the rest as blocks (nested lists, pictures, code). */
+function listItem (lines, o) {
+  const first = []
+  let i = 0
+  while (i < lines.length && lines[i].trim() && !LIST.test(lines[i]) && !/^\s{0,3}(```|~~~)/.test(lines[i])) first.push(lines[i++])
+  const { imgs, words } = picturesOf(first.join('\n'))
+  const rest = lines.slice(i)
+  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null }) : ''}`
+}
+
+function pics (imgs, o) {
+  if (o.picture) return o.picture(imgs)
+  return `<div class="dc-pics">${imgs.map((i) => /^https?:\/\//.test(i.src) || (!i.ref && /^[A-Za-z0-9._/-]+$/.test(i.src)) ? `<img src="${esc(i.src)}" alt="${esc(i.alt)}" loading="lazy">` : `<span class="dc-missing">${esc(i.alt || i.src)}</span>`).join('')}</div>`
+}
+
+// ---------- search ----------
+
+/** Plain words of a page for search and snippets (no Markdown syntax, no pictures, no comments). */
+export function plainText (md) {
+  return frontMatter(md).body.replace(/<!--[\s\S]*?-->/g, ' ').replace(/```[\s\S]*?```/g, ' ').replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/^#+\s+/gm, '').replace(/^\s*([-*+]|\d+[.)])\s+/gm, '').replace(/[`*_>|]/g, '').replace(/\s+/g, ' ').trim()
+}
+
+/** Where `q` occurs in a text: a short snippet around the first hit, or null. Case and accents do not matter. */
+export function snippet (text, q, width = 160) {
+  const fold = (s) => s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase()
+  const words = fold(String(q || '')).split(/\s+/).filter((w) => w.length > 1)
+  if (!words.length) return null
+  const t = String(text || '')
+  const f = fold(t)
+  if (!words.every((w) => f.includes(w))) return null
+  const at = f.indexOf(words[0])
+  const start = Math.max(0, at - Math.floor(width / 3))
+  return `${start ? '…' : ''}${t.slice(start, start + width).trim()}${start + width < t.length ? '…' : ''}`
+}