Lix Plugin .md

Plugin for Lix that tracks changes in Markdown files.

It parses Markdown into the @opral/markdown-wc AST, tracks top-level blocks as entities, and renders rich diffs via HTML Diff.

Installation

npm install @lix-js/sdk @lix-js/plugin-md

Quick start

import { openLix } from "@lix-js/sdk";
import { plugin as markdownPlugin } from "@lix-js/plugin-md";

const lix = await openLix({ providePlugins: [markdownPlugin] });

Insert a Markdown file

const file = await lix.db
	.insertInto("file")
	.values({
		path: "/notes.md",
		data: new TextEncoder().encode(`# Heading\n\nFirst paragraph.`),
	})
	.returningAll()
	.executeTakeFirstOrThrow();

Update the file

await lix.db
	.updateTable("file")
	.set({
		data: new TextEncoder().encode(
			`# Heading\n\nFirst paragraph.\n\nNew note.`,
		),
	})
	.where("id", "=", file.id)
	.execute();

Query file history

Retrieve previous versions of the file:

const history = await lix.db
	.selectFrom("file_history")
	.where("path", "=", "/notes.md")
	.select(["data", "lixcol_commit_id"])
	.execute();

for (const version of history) {
	const content = new TextDecoder().decode(version.data);
	console.log(`Commit ${version.lixcol_commit_id}: ${content}`);
}

Advanced usage

Query all headings in a file

Each markdown block (heading, paragraph, list, etc.) is stored as a structured entity, enabling queries like "get all headings":

const headings = await lix.db
	.selectFrom("state")
	.where("file_id", "=", file.id)
	.where("schema_key", "=", "markdown_wc_heading")
	.select(["entity_id", "snapshot_content"])
	.execute();

for (const heading of headings) {
	const node = heading.snapshot_content;
	const depth = node.depth; // 1-6
	const text = node.children?.[0]?.value;
	console.log(`H${depth}: ${text}`);
}

Query the history of a specific heading

Track how a specific block changed over time using state_history:

// Get the history of a specific heading across all checkpoints
const headingHistory = await lix.db
	.selectFrom("state_history")
	.where("entity_id", "=", headingEntityId)
	.where("schema_key", "=", "markdown_wc_heading")
	.where("root_commit_id", "=", latestCommitId)
	.orderBy("depth", "asc")
	.select(["snapshot_content", "depth", "commit_id"])
	.execute();

for (const state of headingHistory) {
	const text = state.snapshot_content.children?.[0]?.value;
	console.log(`Depth ${state.depth}: "${text}" (commit: ${state.commit_id})`);
}
// Depth 0: "Updated Title" (commit: abc123)
// Depth 1: "Original Title" (commit: def456)

Programmatically update markdown content

Useful for rich-text editing frameworks like TipTap, or AI agents that update slices of a markdown document without rewriting the entire file:

// Update just the heading, leaving other blocks unchanged
await lix.db
	.updateTable("state")
	.set({
		snapshot_content: {
			type: "heading",
			depth: 1,
			data: { id: entityId },
			children: [{ type: "text", value: "Updated Title" }],
		},
	})
	.where("entity_id", "=", entityId)
	.where("schema_key", "=", "markdown_wc_heading")
	.where("file_id", "=", file.id)
	.execute();

// The file content is automatically updated by the plugin

Query document structure

Get the ordered list of block IDs to understand document structure:

const doc = await lix.db
	.selectFrom("state")
	.where("file_id", "=", file.id)
	.where("schema_key", "=", "markdown_wc_document")
	.where("entity_id", "=", "root")
	.select("snapshot_content")
	.executeTakeFirst();

const blockOrder = doc?.snapshot_content?.order; // ["heading_1", "para_1", "para_2"]

Schemas

The plugin uses markdown-wc schemas to represent markdown AST nodes. Each top-level block is stored as an entity with its own schema.

Document order schema

| Schema key | Description | | ---------------------- | -------------------------------------------- | | markdown_wc_document | Stores the order array of block entity IDs |

Block-level schemas (persisted as entities)

| Schema key | Node type | Description | | ---------------------------- | --------------- | ------------------------------------ | | markdown_wc_heading | heading | Heading blocks (h1-h6, depth: 1-6) | | markdown_wc_paragraph | paragraph | Paragraph blocks | | markdown_wc_list | list | List blocks (ordered/unordered) | | markdown_wc_blockquote | blockquote | Blockquote blocks | | markdown_wc_code | code | Fenced code blocks (lang, value) | | markdown_wc_table | table | GFM tables | | markdown_wc_thematic_break | thematicBreak | Horizontal rules | | markdown_wc_html | html | Raw HTML blocks | | markdown_wc_yaml | yaml | YAML frontmatter |

Inline schemas (nested within blocks)

| Schema key | Node type | Description | | ------------------------- | ------------ | ------------------------------------- | | markdown_wc_text | text | Plain text | | markdown_wc_strong | strong | Bold text | | markdown_wc_emphasis | emphasis | Italic text | | markdown_wc_delete | delete | Strikethrough text | | markdown_wc_link | link | Links (url, title) | | markdown_wc_image | image | Images (url, alt, title) | | markdown_wc_inline_code | inlineCode | Inline code | | markdown_wc_break | break | Hard line breaks | | markdown_wc_list_item | listItem | List items (checked for task lists) | | markdown_wc_table_row | tableRow | Table rows | | markdown_wc_table_cell | tableCell | Table cells |

Snapshot content structure

Each block's snapshot_content follows the mdast structure:

// Heading example
{
	type: "heading",
	depth: 2,
	data: { id: "block_abc123" },
	children: [
		{ type: "text", value: "Section Title" }
	]
}

// Paragraph with formatting
{
	type: "paragraph",
	data: { id: "block_def456" },
	children: [
		{ type: "text", value: "This is " },
		{ type: "strong", children: [{ type: "text", value: "bold" }] },
		{ type: "text", value: " text." }
	]
}

// List example
{
	type: "list",
	ordered: false,
	data: { id: "block_ghi789" },
	children: [
		{
			type: "listItem",
			checked: null, // or true/false for task lists
			children: [
				{ type: "paragraph", children: [{ type: "text", value: "Item 1" }] }
			]
		}
	]
}

How it works

• Block-level entities: Each top-level mdast node (paragraphs, headings, lists, tables, code blocks, etc.) is stored as its own entity. The root entity keeps the ordering of those blocks.
• Stable IDs without markup: IDs are minted automatically and kept out of the serialized Markdown, so you do not need to add markers to your documents.
• Nested awareness: Nested nodes (list items, table cells, inline spans) get ephemeral IDs during diffing to align edits but are not persisted as separate entities.
• Similarity-based matching: The detector uses textual similarity and position hints to decide whether a block was edited, moved, inserted, or deleted, even when headings or paragraphs change slightly.
• Apply & render: applyChanges rebuilds Markdown from stored snapshots, and renderDiff produces an HTML diff (using @lix-js/html-diff) that highlights before/after content with data-diff-key markers.

Limitations and tips

• Changes are tracked per top-level block; inline-level differences are aggregated into the parent block.
• Replacing an entire block with unrelated content will be treated as a delete + insert instead of a modification.
• Large documents are supported, but providing reasonably distinct headings/paragraphs improves block matching when content is rearranged.