Plugins Parse plugins

Source

parse_plugins: ParsePlugin[];

Parse plugins change the tree as the parser builds it. A plugin is an object keyed by node type. Each parse function gets the node, and can return a function that runs when the node closes, once everything inside it is known:

const external_links = {
	link: {
		parse(node) {
			return () => {
				if (/^https?:/.test(node.href)) node.attrs.rel = 'noopener';
			};
		}
	}
};

mdsvex({ parse_plugins: [external_links] });
You write
Read the [Svelte docs](https://svelte.dev/docs) or the [guides](/docs/guides).
You get
Compiles to
<p>
  Read the <a
    href="https://svelte.dev/docs"
    rel="noopener">Svelte docs</a
  >
  or the
  <a href="/docs/guides">guides</a>.
</p>

A plugin with sequential: true runs over the finished tree instead, after heading_ids has set its ids.

A sequential plugin can also rewrite text. Its text function is called for each run of text in the document, and run.replace puts text or a node in place of a range of it:

const issues = {
	sequential: true,
	text(run) {
		for (const match of run.text.matchAll(/#(\d+)/g)) {
			const end = match.index + match[0].length;
			run
				.replace(match.index, end, 'link', { href: `/issues/${match[1]}` })
				.append('text', match[0]);
		}
	}
};

mdsvex({ parse_plugins: [issues] });
You write
Fixed in #12 and #14, not in `#13`.
You get
Compiles to
<p>
  Fixed in <a href="/issues/12">#12</a>
  and <a href="/issues/14">#14</a>, not
  in <code>#13</code>.
</p>

A run is whole however the tree split the text, and the text around a replacement stays as you wrote it.

Elements a plugin creates count as markdown, so a replacement for mark also replaces the <mark> a highlight plugin adds.

  • Code, math, urls, attribute values and {expressions} are never in a run, and a character you escaped with a backslash is left out of it.

parse_plugins is the short way to add a few handlers from your config. To ship them with directives and components, or under a name, put the same object in the parse key of a plugin.

Every handler, in parse_plugins or in a plugin, gets a node and a context. Handlers are keyed by node type:

paragraph, heading, emphasis, strong_emphasis, strikethrough, superscript, subscript, code_span, code_fence, link, image, block_quote, list, list_item, table, table_header, table_row, table_cell, thematic_break, hard_break, soft_break, html, html_comment, mustache, svelte_tag, svelte_block, svelte_branch, directive_inline, directive_leaf, directive_container, directive_label, frontmatter and import_statement.

An element or a component is an html node, with its name in attrs.tag and what was written on it in attrs.attributes once it has closed. An expression is a mustache.

The node is a view of the tree as it is being built:

memberwhat it is
typethe node type. Writing it changes what the node renders as
attrsits attributes. Writing one sets it on the element, or passes it to a replacement as a prop
text_contentthe text inside it
parent, first_child, last_child, next, previts neighbours, each a node or null
depth, href, title, info, math, ordered, start, tightwhat its type has: the depth of a heading, the url of a link, the info string of a fence
position{ start, end }, each with an offset, a line and a column. offset is a string index, in UTF-16 code units, into the source with every \r\n made a \n. end is not set until the node closes
pendingtrue while the parser may still take the node back
prepend(type, attrs), append(type, attrs)adds a child and returns it. For 'text' the second argument is the text
wrap_inner(type, attrs)puts a new node between the node and its children
wrap_from(type, attrs)puts a new node around the node and every sibling after it, until you call close() on what it returns
remove()takes the node out of the tree

A new html node takes its element name as tag. This wraps each ## heading and what follows it in a <section>:

const sections = {
	name: 'sections',
	heading: {
		parse(node, ctx) {
			if (node.depth !== 2 || node.parent?.type !== 'root') return;
			ctx.scratch.section?.close();
			ctx.scratch.section = node.wrap_from('html', { tag: 'section' });
		}
	}
};

mdsvex({ parse_plugins: [sections] });
You write
## One

First.

## Two

Second.
You get
Compiles to
<section>
  <h2>One</h2>
  <p>First.</p>
</section>
<section>
  <h2>Two</h2>
  <p>Second.</p>
</section>

The context is new for each document. What a plugin keeps between its handlers goes in ctx.scratch, as the open section does above.

  • One object for each plugin name and document. Every handler, close callback, deferred task and document hook of the plugin gets the same one, so the bound handlers of a plugin can leave something for its document hook. It needs a name.
  • It is the plugin's own. Anything can go in it, and it never reaches the page or plugin_data.
  • The parser does not take it back. When the parser takes a node back, what its handlers put in the scratch stays. Keep there what that can't make wrong, such as directives and headings, and write what must follow it with ctx.set and ctx.add.

The context also has:

memberwhat it is
ctx.filenamethe path of the document
ctx.frontmatterthe parsed frontmatter, undefined when the document has none. Don't write to it
ctx.warn(code, message, node)reports a problem. The build prints it with the line of the node
ctx.set(key, value), ctx.add(key, value)write what the plugin leaves for the page, see plugin data. They need a name
ctx.datawhat the plugin has written so far, read-only
const one_title = {
	name: 'one_title',
	parse: {
		heading: {
			parse(node, ctx) {
				if (node.depth === 1 && ctx.frontmatter?.title !== undefined) {
					ctx.warn('two_titles', `${ctx.filename} has a title and a # heading`, node);
				}
			}
		}
	}
};

mdsvex({ plugins: [one_title] });

A handler bound to a directive has the same members beside directive, index and state. Its children table also takes '*', a handler for a child of any type, which runs after the one for its type.

The parser opens some nodes on a guess, such as an emphasis before it has seen the closing _ or a link before its url. When the guess is wrong it takes the node back, and everything a handler did for that node is undone. node.pending is true for such a node.

A plugin sees the text as written. smart_punctuation is applied when the page renders, after every handler.

  • wrap_from needs a node that is not pending. Headings and block directives never are. For a link or an emphasis, call it from the function the handler returns, which runs once the node has closed.
  • Handlers are synchronous. For work that waits, see deferred work below. A plugin can't add syntax either, only change the tree the parser made.

remove() works where nothing can ask for the node back: in the function a handler returns, for a node that is not pending, or anywhere in a sequential plugin. A node removes itself or something inside it.

// comments do not reach the page
const no_comments = {
	html_comment: {
		parse: (node) => () => node.remove()
	}
};

mdsvex({ parse_plugins: [no_comments] });
You write
<!-- a draft, not ready -->

Ready.
You get
Compiles to
<p>Ready.</p>

PLUGINS.md in the repository has the whole API, with what a revoke undoes and how handlers run over a stream.

mdsvex, markdown with Svelte in it. MIT licence.