@abraca/convert

The canonical Markdown ↔ Yjs/TipTap round-trip converter — shared by cou-sh, abracadabra-nuxt, and @abraca/mcp instead of each vendoring its own copy. Zero runtime dependencies (yjs peer-only).

Documentation

Full, code-derived documentation lives in docs/ — the node/mark spec, the universal-meta spec, the conversion API, diff + file-blocks, and a precise fidelity/gotchas reference. It is the source of truth (the old SPEC.md was untrusted and removed).

API

import { populateYDocFromMarkdown, yjsToMarkdown } from "@abraca/convert";
populateYDocFromMarkdown(doc.getXmlFragment("default"), markdown);
const { title, markdown } = /* via */ yjsToMarkdown(fragment, label);

Fragment shape: [documentHeader, documentMeta, ...body]. Also populateYDocFromHtml (needs a global DOMParser), yjsToHtml, yjsToPlainText, structural diff.ts, and the FS-sync file-blocks/ sidecar.

::

Attach-before-fill is load-bearing — Y.XmlText.insert on a detached node reverses text (YATA clock 0). Coverage is partial: several spec nodes/marks have no runtime branch, and frontmatter handles a ~13-key subset. See docs/4.reference/.

License

MIT.