@abraca/convert 2.23.0 → 2.24.0

package/dist/index.d.ts

@@ -97,6 +97,19 @@ declare function populateYDocFromMarkdown(fragment: Y.XmlFragment, markdown: str
 //#endregion
 //#region packages/convert/src/yjs-to-markdown.d.ts
 declare function yjsToMarkdown(fragment: Y.XmlFragment, label: string, meta?: DocPageMeta, type?: string): string;
+/**
+ * Make a serialised doc self-describing for an Obsidian-style vault or a
+ * markdown export: the doc's label is always present as a leading `# Title`,
+ * even when the body is empty (containers, kanban columns) — that's how the
+ * app shows it, and it makes the label round-trip losslessly (the parser
+ * maps a leading H1 → the doc title) with zero sidecar dependency.
+ *
+ * Pure post-process of yjsToMarkdown's output; the serializer's own
+ * byte-stability invariants are untouched. Originally lived in cou-sh's
+ * fs-sync (useFsSyncTo) — lifted here so fs-sync and doc export share one
+ * implementation.
+ */
+declare function ensureLeadingTitle(md: string, label: unknown): string;
 /**
  * Walk the Y.XmlFragment and concatenate all text content with no
  * markup or frontmatter. Block boundaries become newlines. Useful for
@@ -408,4 +421,4 @@ declare function getTreeData(treeMap: any): Record<string, FsTreeEntry>;
  */
 declare function nextOrder(treeData: Record<string, FsTreeEntry>, parentId: string | null): number;
 //#endregion
-export { CODE_TEXT_KEY, type DocPageMeta, type FrontmatterResult, type FsAdapter, type FsSyncManifest, type FsTreeEntry, type JsonAttr, MARK_SPECS, MARK_SPEC_BY_DELIM, MARK_SPEC_BY_NAME, type ManifestEntry, type MarkAttrSpec, type MarkSpec, type MarkWireKind, type MetaValueType, NODE_SPECS, NODE_SPEC_BY_NAME, type NodeAttrSpec, type NodeSpec, type NodeWireKind, UNIVERSAL_META_KEYS, UNIVERSAL_META_KEY_NAMES, type UniversalMetaKey, type UploadManifestEntry, type YjsDiff, type YjsJsonElement, type YjsJsonNode, type YjsJsonText, type YjsTextRun, appendHtmlToFragment, buildAliasMap, buildRelativePath, buildReverseLookup, codeCompanionPath, codeFileExtension, conflictsDir, createEmptyManifest, diffJson, diffYjs, extToLanguage, filenameToLabel, fsFilenameToLabel, getDocDir, getFsAdapter, getTreeData, hasChildren, inferCodeMetaFromFilename, isCodeExtension, jsonToYFragment, labelToFilename, languageToExtension, loadManifest, lookupByDocId, lookupByHash, lookupByPath, manifestDir, mdcTagOf, nextOrder, normalizeExtension, orphansDir, parseFrontmatter, populateYDocFromHtml, populateYDocFromMarkdown, readCodeText, removeEntry, resolveParentFromPath, saveManifest, setEntry, setFsAdapter, simpleHash, stringifyJsonNode, trashDir, writeCodeText, yfragmentToJson, yjsToHtml, yjsToMarkdown, yjsToPlainText };
+export { CODE_TEXT_KEY, type DocPageMeta, type FrontmatterResult, type FsAdapter, type FsSyncManifest, type FsTreeEntry, type JsonAttr, MARK_SPECS, MARK_SPEC_BY_DELIM, MARK_SPEC_BY_NAME, type ManifestEntry, type MarkAttrSpec, type MarkSpec, type MarkWireKind, type MetaValueType, NODE_SPECS, NODE_SPEC_BY_NAME, type NodeAttrSpec, type NodeSpec, type NodeWireKind, UNIVERSAL_META_KEYS, UNIVERSAL_META_KEY_NAMES, type UniversalMetaKey, type UploadManifestEntry, type YjsDiff, type YjsJsonElement, type YjsJsonNode, type YjsJsonText, type YjsTextRun, appendHtmlToFragment, buildAliasMap, buildRelativePath, buildReverseLookup, codeCompanionPath, codeFileExtension, conflictsDir, createEmptyManifest, diffJson, diffYjs, ensureLeadingTitle, extToLanguage, filenameToLabel, fsFilenameToLabel, getDocDir, getFsAdapter, getTreeData, hasChildren, inferCodeMetaFromFilename, isCodeExtension, jsonToYFragment, labelToFilename, languageToExtension, loadManifest, lookupByDocId, lookupByHash, lookupByPath, manifestDir, mdcTagOf, nextOrder, normalizeExtension, orphansDir, parseFrontmatter, populateYDocFromHtml, populateYDocFromMarkdown, readCodeText, removeEntry, resolveParentFromPath, saveManifest, setEntry, setFsAdapter, simpleHash, stringifyJsonNode, trashDir, writeCodeText, yfragmentToJson, yjsToHtml, yjsToMarkdown, yjsToPlainText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/convert",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "description": "Bullet-proof Markdown ↔ Yjs/TipTap round-trip — canonical converter shared by cou-sh, abracadabra-nuxt, and @abraca/mcp.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -15,7 +15,7 @@ export {
   type FrontmatterResult,
 } from './markdown-to-yjs.ts'
 
-export { yjsToMarkdown, yjsToHtml, yjsToPlainText } from './yjs-to-markdown.ts'
+export { yjsToMarkdown, yjsToHtml, yjsToPlainText, ensureLeadingTitle } from './yjs-to-markdown.ts'
 
 export {
   populateYDocFromHtml,

package/src/markdown-to-yjs.ts

@@ -1,5 +1,11 @@
 import * as Y from 'yjs'
 import type { DocPageMeta } from './types.ts'
+import {
+  buildAliasMap,
+  UNIVERSAL_META_KEYS,
+  type UniversalMetaKey,
+  type MetaValueType,
+} from './spec/universal-meta.ts'
 
 // ── Filename → readable label ────────────────────────────────────────────────
 
@@ -160,6 +166,28 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
     if (!Number.isNaN(n)) meta.rating = Math.min(5, Math.max(0, n))
   }
 
+  // ── Generic spec-driven pass ──
+  // Everything the hand-rolled section above didn't consume: map through
+  // the universal-meta alias map and coerce by the spec's value type, so
+  // graph/map/spatial/dashboard layout, covers, datetimes etc. survive
+  // import instead of being silently dropped. Unknown custom keys are
+  // preserved with best-effort coercion; internal `_`-keys are ignored.
+  for (const [rawKey, rawVal] of Object.entries(raw)) {
+    if (CONSUMED_FM_KEYS.has(rawKey)) continue
+    if (rawKey.startsWith('_')) continue
+    const canonical = FM_ALIAS_MAP.get(rawKey)
+    if (canonical) {
+      if (canonical === 'title' || canonical === 'type') continue
+      if ((meta as Record<string, unknown>)[canonical] !== undefined) continue
+      const spec = FM_SPEC_BY_KEY.get(canonical)
+      const coerced = coerceMetaValue(rawVal, spec?.type)
+      if (coerced !== undefined) (meta as Record<string, unknown>)[canonical] = coerced
+    } else {
+      const coerced = coerceMetaValue(rawVal, undefined)
+      if (coerced !== undefined) (meta as Record<string, unknown>)[rawKey] = coerced
+    }
+  }
+
   const rawTitle = typeof raw['title'] === 'string' ? raw['title'] : undefined
   const title = rawTitle !== undefined ? stripQuotes(rawTitle) : undefined
   const type = getStr(['type'])
@@ -167,6 +195,72 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
   return { title, type, meta, body }
 }
 
+/** Raw YAML keys the hand-rolled section of parseFrontmatter consumes. */
+const CONSUMED_FM_KEYS: ReadonlySet<string> = new Set([
+  'title', 'type', 'tags', 'color', 'icon', 'status', 'priority',
+  'checked', 'done', 'dateStart', 'date', 'created', 'dateEnd', 'due',
+  'subtitle', 'description', 'url', 'language', 'fileExtension',
+  'codeTheme', 'rating',
+])
+
+const FM_ALIAS_MAP: ReadonlyMap<string, string> = buildAliasMap()
+const FM_SPEC_BY_KEY: ReadonlyMap<string, UniversalMetaKey> = new Map(
+  UNIVERSAL_META_KEYS.map(k => [k.key, k]),
+)
+
+/**
+ * Coerce a raw YAML scalar/array to the spec's value type. With no spec
+ * (custom key) the coercion is best-effort: booleans and numbers are
+ * recognised by shape, everything else stays a string. Returns undefined
+ * when the value can't be represented (caller skips the key).
+ */
+function coerceMetaValue(
+  rawVal: string | string[],
+  specType: MetaValueType | undefined,
+): unknown {
+  if (Array.isArray(rawVal)) return rawVal
+  const v = rawVal
+  if (v === '') return undefined
+  switch (specType) {
+    case 'number':
+    case 'integer': {
+      const n = Number(v)
+      return Number.isFinite(n) ? n : undefined
+    }
+    case 'boolean':
+      return v === 'true'
+    case 'string[]':
+      return [v]
+    case 'members':
+    case 'json': {
+      try {
+        return JSON.parse(v)
+      } catch {
+        return undefined
+      }
+    }
+    case 'string':
+    case 'string-enum':
+    case 'iso-date':
+    case 'iso-datetime':
+    case 'hh-mm':
+      return v
+    case undefined: {
+      // Custom key — recognise booleans/numbers/JSON payloads by shape
+      // (quotes were already stripped when the raw map was built).
+      if (v === 'true') return true
+      if (v === 'false') return false
+      if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+      if (v.startsWith('{')) {
+        try {
+          return JSON.parse(v)
+        } catch { /* fall through to string */ }
+      }
+      return v
+    }
+  }
+}
+
 // ── Inline token parsing ─────────────────────────────────────────────────────
 
 interface InlineToken {
@@ -444,6 +538,7 @@ function consumeList(
 
     // Consume continuation: lines indented deeper than `indent`.
     const contLines: string[] = []
+    let contMinIndent = Infinity
     while (i < lines.length) {
       const next = lines[i]!
       if (next.trim() === '') {
@@ -461,13 +556,23 @@ function consumeList(
       }
       const nextIndent = leadingSpaces(next)
       if (nextIndent <= indent) break
-      // De-indent by exactly 2 to match the canonical wire form.
-      const deindentBy = Math.min(nextIndent, indent + 2)
-      contLines.push(next.slice(deindentBy))
+      if (nextIndent < contMinIndent) contMinIndent = nextIndent
+      contLines.push(next)
       i++
     }
     if (contLines.length > 0) {
-      item.innerBlocks = parseBlocks(contLines.join('\n'))
+      // De-indent the whole continuation block by its common minimum
+      // indent (not a fixed `indent + 2`): CommonMark nests 3 columns
+      // under `1. ` markers, so clamping at 2 left a 1-space residue
+      // that parseBlocks read as paragraph text — merging nested list
+      // items onto a single line. Stripping the common indent keeps
+      // relative structure for deeper levels and lands the first nested
+      // marker at column 0, where parseBlocks recognises it. Canonical
+      // wire-form input (exactly `indent + 2`) strips identically.
+      const deindentBy = contMinIndent === Infinity ? 0 : contMinIndent
+      item.innerBlocks = parseBlocks(
+        contLines.map(l => l.slice(deindentBy)).join('\n')
+      )
     }
     items.push(item)
   }

package/src/yjs-to-markdown.ts

@@ -1,5 +1,10 @@
 import * as Y from 'yjs'
 import type { DocPageMeta } from './types.ts'
+import {
+  UNIVERSAL_META_KEYS,
+  UNIVERSAL_META_KEY_NAMES,
+  type MetaValueType,
+} from './spec/universal-meta.ts'
 
 // ── Cross-yjs-copy node typing ───────────────────────────────────────────────
 //
@@ -357,25 +362,24 @@ function serializeListItems(el: Y.XmlElement, type: 'bullet' | 'ordered', indent
     if (!(isXElem(child)) || child.nodeName !== 'listItem') continue
     const prefix = type === 'bullet' ? '- ' : `${counter++}. `
     // A listItem may contain paragraphs and nested lists
-    const subParts: string[] = []
+    const subParts: Array<{ text: string, isList: boolean }> = []
     for (const sub of child.toArray()) {
       if (!(isXElem(sub))) continue
       if (sub.nodeName === 'bulletList') {
-        subParts.push(serializeListItems(sub, 'bullet', indent + '  '))
+        subParts.push({ text: serializeListItems(sub, 'bullet', indent + '  '), isList: true })
       } else if (sub.nodeName === 'orderedList') {
-        subParts.push(serializeListItems(sub, 'ordered', indent + '  '))
+        subParts.push({ text: serializeListItems(sub, 'ordered', indent + '  '), isList: true })
       } else {
-        subParts.push(serializeInline(sub))
+        subParts.push({ text: serializeInline(sub), isList: false })
       }
     }
-    if (subParts.length <= 1) {
-      lines.push(`${indent}${prefix}${subParts[0] ?? ''}`)
-    } else {
-      lines.push(`${indent}${prefix}${subParts[0] ?? ''}`)
-      for (let i = 1; i < subParts.length; i++) {
-        // Nested lists are already indented; plain text gets continuation indent
-        lines.push(subParts[i]!)
-      }
+    lines.push(`${indent}${prefix}${subParts[0]?.text ?? ''}`)
+    for (let i = 1; i < subParts.length; i++) {
+      const part = subParts[i]!
+      // Nested lists are already indented; plain-text continuation gets
+      // the item's content indent so it stays inside the listItem on
+      // re-parse instead of escaping as a sibling paragraph.
+      lines.push(part.isList ? part.text : `${indent}  ${part.text}`)
     }
   }
   return lines.join('\n')
@@ -479,6 +483,52 @@ function serializeSlottedContainer(
 
 // ── Frontmatter generation ──────────────────────────────────────────────────
 
+/**
+ * Keys the hand-rolled canonical section below emits itself. The generic
+ * spec-driven pass must skip these so each key is serialised exactly once,
+ * in the canonical order existing fixtures depend on.
+ */
+const CANONICAL_FM_KEYS: ReadonlySet<string> = new Set([
+  'title', 'type', 'tags', 'color', 'icon', 'status', 'priority', 'checked',
+  'language', 'fileExtension', 'codeTheme', 'dateStart', 'dateEnd',
+  'subtitle', 'url', 'rating',
+])
+
+/** Render one meta value as a YAML line, or null when it can't be emitted. */
+function yamlLine(key: string, v: unknown, specType?: MetaValueType): string | null {
+  if (v === undefined || v === null) return null
+  if (Array.isArray(v)) {
+    if (v.length === 0) return null
+    return `${key}: [${v.map(x => String(x)).join(', ')}]`
+  }
+  if (typeof v === 'number') return Number.isFinite(v) ? `${key}: ${v}` : null
+  if (typeof v === 'boolean') return `${key}: ${v}`
+  if (typeof v === 'string') return v === '' ? null : `${key}: ${yamlScalar(v)}`
+  if (specType === 'members' || specType === 'json' || typeof v === 'object') {
+    // Structured value — emit as single-quoted JSON (parse side JSON.parses
+    // it back). Skip when the payload itself contains a single quote rather
+    // than emit un-round-trippable YAML.
+    try {
+      const json = JSON.stringify(v)
+      return json.includes('\'') ? null : `${key}: '${json}'`
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/**
+ * Generate the YAML frontmatter block. Returns '' when there is nothing to
+ * emit, so callers can skip the block entirely — an empty `---\n\n---` shell
+ * is never produced (docs whose meta holds only internal `_`-keys used to
+ * export as exactly that junk).
+ *
+ * Emission order: the long-standing hand-rolled canonical keys first (byte
+ * stability for existing files), then every remaining universal-meta key in
+ * registry order, then custom keys alphabetically. Internal keys (leading
+ * `_`, e.g. `_metaInitialized`) are never serialised.
+ */
 function generateFrontmatter(label: string | undefined, meta?: DocPageMeta, type?: string): string {
   const lines: string[] = []
 
@@ -488,32 +538,54 @@ function generateFrontmatter(label: string | undefined, meta?: DocPageMeta, type
     lines.push(`type: ${type}`)
   }
 
-  if (!meta) return `---\n${lines.join('\n')}\n---`
-
-  if (meta.tags?.length) {
-    lines.push(`tags: [${meta.tags.join(', ')}]`)
-  }
-  if (meta.color) lines.push(`color: ${yamlScalar(meta.color)}`)
-  if (meta.icon) lines.push(`icon: ${yamlScalar(meta.icon)}`)
-  if (meta.status) lines.push(`status: ${yamlScalar(meta.status)}`)
-
-  if (meta.priority !== undefined && meta.priority !== 0) {
-    const map: Record<number, string> = { 1: 'low', 2: 'medium', 3: 'high', 4: 'urgent' }
-    lines.push(`priority: ${map[meta.priority] ?? meta.priority}`)
+  if (meta) {
+    if (meta.tags?.length) {
+      lines.push(`tags: [${meta.tags.join(', ')}]`)
+    }
+    if (meta.color) lines.push(`color: ${yamlScalar(meta.color)}`)
+    if (meta.icon) lines.push(`icon: ${yamlScalar(meta.icon)}`)
+    if (meta.status) lines.push(`status: ${yamlScalar(meta.status)}`)
+
+    if (meta.priority !== undefined && meta.priority !== 0) {
+      const map: Record<number, string> = { 1: 'low', 2: 'medium', 3: 'high', 4: 'urgent' }
+      lines.push(`priority: ${map[meta.priority] ?? meta.priority}`)
+    }
+
+    if (meta.checked !== undefined) lines.push(`checked: ${meta.checked}`)
+    // Code page type: syntax-highlight language + on-disk extension. These
+    // round-trip the `.md` envelope so the companion code file can be re-derived.
+    if (meta.language) lines.push(`language: ${yamlScalar(meta.language)}`)
+    if (meta.fileExtension) lines.push(`fileExtension: ${yamlScalar(meta.fileExtension)}`)
+    if (meta.codeTheme) lines.push(`codeTheme: ${yamlScalar(meta.codeTheme)}`)
+    if (meta.dateStart) lines.push(`dateStart: "${escapeYaml(meta.dateStart)}"`)
+    if (meta.dateEnd) lines.push(`dateEnd: "${escapeYaml(meta.dateEnd)}"`)
+    if (meta.subtitle) lines.push(`subtitle: "${escapeYaml(meta.subtitle)}"`)
+    if (meta.url) lines.push(`url: ${meta.url}`)
+    if (meta.rating !== undefined && meta.rating !== 0) lines.push(`rating: ${meta.rating}`)
+
+    // Spec-driven pass: every other universal key, in registry order, so
+    // graph/map/spatial/dashboard layout, covers, datetimes etc. survive
+    // export instead of being silently dropped.
+    const m = meta as Record<string, unknown>
+    for (const spec of UNIVERSAL_META_KEYS) {
+      if (CANONICAL_FM_KEYS.has(spec.key)) continue
+      const line = yamlLine(spec.key, m[spec.key], spec.type)
+      if (line) lines.push(line)
+    }
+
+    // Custom (non-spec) keys, alphabetically; internal `_`-keys skipped.
+    const customKeys = Object.keys(m)
+      .filter(k => !k.startsWith('_')
+        && !CANONICAL_FM_KEYS.has(k)
+        && !UNIVERSAL_META_KEY_NAMES.has(k))
+      .sort()
+    for (const k of customKeys) {
+      const line = yamlLine(k, m[k])
+      if (line) lines.push(line)
+    }
   }
 
-  if (meta.checked !== undefined) lines.push(`checked: ${meta.checked}`)
-  // Code page type: syntax-highlight language + on-disk extension. These
-  // round-trip the `.md` envelope so the companion code file can be re-derived.
-  if (meta.language) lines.push(`language: ${yamlScalar(meta.language)}`)
-  if (meta.fileExtension) lines.push(`fileExtension: ${yamlScalar(meta.fileExtension)}`)
-  if (meta.codeTheme) lines.push(`codeTheme: ${yamlScalar(meta.codeTheme)}`)
-  if (meta.dateStart) lines.push(`dateStart: "${escapeYaml(meta.dateStart)}"`)
-  if (meta.dateEnd) lines.push(`dateEnd: "${escapeYaml(meta.dateEnd)}"`)
-  if (meta.subtitle) lines.push(`subtitle: "${escapeYaml(meta.subtitle)}"`)
-  if (meta.url) lines.push(`url: ${meta.url}`)
-  if (meta.rating !== undefined && meta.rating !== 0) lines.push(`rating: ${meta.rating}`)
-
+  if (lines.length === 0) return ''
   return `---\n${lines.join('\n')}\n---`
 }
 
@@ -714,9 +786,6 @@ export function yjsToMarkdown(
   const effectiveMeta = meta ?? docMeta.meta
   const effectiveType = type ?? docMeta.type
 
-  const metaIsEmpty = isMetaEmpty(effectiveMeta)
-  const typeIsDefault = !effectiveType || effectiveType === 'doc'
-
   const bodyBlocks = collectBodyBlocks(fragment)
 
   // Body assembly — when the parser captured the title from a body H1
@@ -730,13 +799,13 @@ export function yjsToMarkdown(
     body = serializeBlocksClean(bodyBlocks)
   }
 
-  const wantFrontmatterTitle = titleSource === 'frontmatter'
-  const wantFrontmatterMeta = !metaIsEmpty || !typeIsDefault
-  if (!wantFrontmatterTitle && !wantFrontmatterMeta) {
+  const fmTitle = titleSource === 'frontmatter' ? effectiveTitle : undefined
+  // The generator returns '' when there is nothing to emit — never an
+  // empty `---\n\n---` shell (e.g. meta holding only internal `_`-keys).
+  const frontmatter = generateFrontmatter(fmTitle, effectiveMeta, effectiveType)
+  if (frontmatter === '') {
     return body === '' ? '' : `${body}\n`
   }
-  const fmTitle = wantFrontmatterTitle ? effectiveTitle : undefined
-  const frontmatter = generateFrontmatter(fmTitle, effectiveMeta, effectiveType)
   if (body === '') return `${frontmatter}\n`
   return `${frontmatter}\n\n${body}\n`
 }
@@ -800,16 +869,46 @@ function serializeBlocksClean(blocks: Y.XmlElement[]): string {
   return parts.join('\n\n')
 }
 
-function isMetaEmpty(meta: DocPageMeta | undefined): boolean {
-  if (!meta) return true
-  for (const key of Object.keys(meta)) {
-    const v = (meta as Record<string, unknown>)[key]
-    if (v === undefined || v === null) continue
-    if (typeof v === 'string' && v === '') continue
-    if (Array.isArray(v) && v.length === 0) continue
-    return false
+/**
+ * Make a serialised doc self-describing for an Obsidian-style vault or a
+ * markdown export: the doc's label is always present as a leading `# Title`,
+ * even when the body is empty (containers, kanban columns) — that's how the
+ * app shows it, and it makes the label round-trip losslessly (the parser
+ * maps a leading H1 → the doc title) with zero sidecar dependency.
+ *
+ * Pure post-process of yjsToMarkdown's output; the serializer's own
+ * byte-stability invariants are untouched. Originally lived in cou-sh's
+ * fs-sync (useFsSyncTo) — lifted here so fs-sync and doc export share one
+ * implementation.
+ */
+export function ensureLeadingTitle(md: string, label: unknown): string {
+  const title = typeof label === 'string' ? label.trim() : ''
+
+  // Peel an optional leading frontmatter block off the body.
+  let fm = ''
+  let body = md
+  const fmMatch = /^---\n([\s\S]*?)\n---\n?/.exec(md)
+  if (fmMatch) {
+    body = md.slice(fmMatch[0].length)
+    // Collapse an empty frontmatter (only whitespace between fences).
+    fm = (fmMatch[1] ?? '').trim() === '' ? '' : `---\n${fmMatch[1]}\n---`
+  }
+  body = body.replace(/^\n+/, '')
+
+  if (!title) {
+    const out = fm ? (body ? `${fm}\n\n${body}` : `${fm}\n`) : body
+    return out && !out.endsWith('\n') ? `${out}\n` : out
   }
-  return true
+
+  // A leading ATX H1 is already the title (the serializer emitted
+  // headerText||label via titleSource:'h1') — leave it, never double it.
+  const hasH1 = /^#[ \t]+\S/.test(body)
+  let out = hasH1
+    ? body
+    : (body ? `# ${title}\n\n${body}` : `# ${title}\n`)
+  if (fm) out = `${fm}\n\n${out}`
+  if (!out.endsWith('\n')) out += '\n'
+  return out
 }
 
 /**