GrMarkdown

The html prop has two values: escape (the default) shows the markup as text, strip throws it away. There is no third one and there will not be — it would require v-html, which does not occur in the repository even once.

This is not caution but a consequence of the design: the tree is assembled from Vue nodes rather than from an HTML string, and the escaping is done by Vue itself. There is no sanitiser in the package because there is no need for one — along with the class of defects it is usually put in for.

The flip side is named directly: a <div> inside markdown will remain text. Whoever needs HTML itself replaces the renderer of the html node through components and takes the responsibility on themselves.

javascript:, data:, vbscript: and everything that is not in allowedProtocols do not reach the markup — the link becomes plain text. The check runs after the entities are expanded and the insignificant characters are cleaned out: javascript: and a tab in the middle of the scheme are executed by the browser, and a naive startsWith does not catch them.

An external link gets rel="nofollow noopener noreferrer"; target is not imposed — it is set by linkTarget.

The document is divided into top-level blocks, each keyed by its own source text. A block whose text has not changed returns the same VNode object, and Vue skips it whole, neither comparing nor touching the DOM.

Hence two properties: an edit of a paragraph in an article of a hundred kilobytes costs one paragraph, and an insertion of a block at the beginning does not recreate what is below — the key is computed from the text rather than from the position.

Virtualisation — a rendering window — is wrong here: along with the invisible nodes it takes away search on the page, the jump by an anchor into a section not shown, a selection across the whole document and printing. A document in which Ctrl+F does not find a word stops being a document.

So everything lives in the DOM, and only the layout and the painting are lifted off the blocks — through content-visibility. The height of each block is estimated by its content, otherwise the scrollbar would jump while scrolling.

The id of a heading is the slug of its text rather than useId(). This departure from the general rule is deliberate: useId would give different identifiers to two renders of the same document, and a link like #section from the address bar or from a letter would stop working.

There is nothing to tell two documents on one page apart with except idPrefix — so that is what is set. headingOffset shifts the levels when the document is embedded into a page where h1 is already taken.

The marker of an alert is parsed only into a tone. The look of the message — the fill, the border, the icon, the type size — comes from GrConfigProvider, and the component imposes no variant of its own: otherwise an alert in a document would look different from the same alert on the page next to it. The title of the tone (Note, Warning, …) is taken from the locale of the package — the tone must read as text, not only as colour.

These messages have no live-region role: live="off". role="alert" interrupts the reading of a screen reader, and a message inside an article has no such right.

The rest — heading, paragraph, list, quote, link, rule, code block — remains semantic markup on its own tokens: an edge mixes the whole CSS and safelist of the donor into the consumer, and a document of nothing but paragraphs must not pay for what is not in it.

The exceptions are made where a copy of its own would set a visual contract that belongs to the core: the tone and the icon of a message, the look of a check mark, the scroll area and the header of a table — decisions of the design system rather than of the document.

The link did not get here by measurement rather than by taste: it is the most frequent inline node, and on a document of three hundred links the GrLink instances give a fourfold render time. Whoever needs its full contract sets components.link and pays knowingly.

The alert at the same time goes live="off": role="alert" interrupts the reading of a screen reader, and a message inside an article has no such right. The meaning of the tone is carried by the caption in text, not only by the colour.

The engine accepts extensions, and that is the only way to add syntax that is not in the set:

const engine = createMarkedEngine({ extensions: [katexExtension] })

Only the tokenizer is taken from the extension. Its renderer is never called: the markup is built by renderNodes from Vue nodes, and no HTML string arises in the package at all. A new type of token arrives as a custom node, and it is drawn by the component from components by the name of the token:

<GrMarkdown :source="text" :engine="engine" :components="{ inlineMath: Formula }" />

The component receives name, raw and all the token’s own fields as props, and the parsed content as the default slot. If there is no component under that name, the source is printed as text: silently losing what the author wrote is not allowed.

That is how marked-katex-extension, marked-emoji, marked-directive are plugged in — without giving the package a single dependency.

Example: highlighting with a marker

==text== is highlighting with a marker, familiar from Obsidian and Pandoc. There is no such syntax in either CommonMark or GFM, so without an extension the parser does not recognise it and the equals signs themselves stay on the screen. Twenty lines close the question entirely:

import { createMarkedEngine } from '@feugene/granularity-editor/markdown'

const highlightMark = {
  name: 'highlightMark',
  level: 'inline' as const,
  start: (src: string) => src.indexOf('=='),
  tokenizer(src: string) {
    const match = /^==([^=\n]+)==/.exec(src)
    return match ? { type: 'highlightMark', raw: match[0], value: match[1] } : undefined
  },
}

const engine = createMarkedEngine({ extensions: [highlightMark] })

<script setup lang="ts">
import { h } from 'vue'

const Mark = (props: { value: string }) => h('mark', props.value)
</script>

<template>
  <GrMarkdown :source="text" :engine="engine" :components="{ highlightMark: Mark }" />
</template>

The name of the component in components matches the name of the token. The fields of the token arrive as props: here it is value, for a maths token it would be the formula. Remove the component — and ==text== becomes text again rather than disappearing.

A fence with the mermaid language is an ordinary code node, and it is drawn by whatever component lies in components.code. The package does not know a single line about mermaid and will not: the engine weighs more than the whole design system, and documents without a single diagram would be obliged to pay for it too.

The renderer decides by the language and hands everything else to the default renderer:

const MermaidBlock = defineComponent({
  props: { code: String, language: String, wrap: Boolean },
  setup(props) {
    // ...the drawing in onMounted, see the demo on the showcase
    return () => props.language === 'mermaid'
      ? h('figure', { ref: host })
      : h(GrMarkdownCode, { code: props.code, language: props.language, wrap: props.wrap })
  },
})

Three things in this wiring are not cosmetics, and each is worth its money.

The import is dynamic only. A static import 'mermaid' puts the engine into the shared chunk, and it is downloaded by everyone who opened a page with a document.

layout: 'dagre' in the config. Without this line mermaid pulls in the ELK layout on the very first flowchart — even though it is dagre that draws it. The measurement (12.0.0, what actually went over the network, gzip):

One line of config — minus 430 KB and a first frame five times faster.

securityLevel: 'strict'. The engine builds the SVG itself, and the labels in it come from markdown, that is, from outside. strict cleans the markup out of them; this is exactly the boundary for the sake of which there is no v-html in the package itself.

Further on each type of diagram pays for itself separately: sequence — plus 31 KB, class — 16 KB, state — 14 KB, pie — 154 KB. A repeated paint of a type already loaded: flowchart — 84 ms, sequence — 28 ms, class — 71 ms, pie — 16 ms. A dozen diagrams on a page is a noticeable fraction of a second, so it is better to draw them as they enter the viewport rather than all at once.

The needed type of diagram does not have to be plugged in

The built-in types — flowchart, sequence, class, state, pie, gantt, er, journey and the rest — arrive on their own: render() pulls in the grammar of the type it met at the very first paint. Hence the spread of prices above — whoever drew pays.

Registration is needed only for what is not in the engine:

The primary sources, which are also the answer to “and how do I configure this”:

• the syntax of all diagram types;
• the configuration in full — securityLevel and layout are there too;
• the theme and themeVariables — with them the diagram sits on the tokens of the design system;
• layouts and ELK;
• the render and initialize API.

The colour for themeVariables is taken from a token in two steps, and that is not a whim: getPropertyValue returns the declared value, and part of the palette is declared through color-mix(); the computed value, in turn, Chrome returns as color(srgb …), which the colour parser inside mermaid does not understand either. The working trick is to assign the colour to a probe element, read the computed one and normalise it with a canvas; the ready code is in the demo on the showcase.

And the second trap is right there: themeVariables is obeyed only by the base theme. The built-in ones (default, neutral, forest, dark) set the palette themselves, and mixing tokens into them gives a blend of two decisions instead of either. Either base plus variables of your own — then the diagram switches along with the theme of the page — or a built-in theme in full.

The mermaid syntax is not the only one possible: the seam knows nothing about it. For comparison, nomnoml weighs 24 KB gzip and draws in 3.4 ms, but speaks its own language, and what was written for mermaid it will not understand. The choice between them is the application’s choice rather than the package’s; one component will have to be changed.

Three values, and they differ in what counts as markup at all rather than in how it looks.

gfm (the default) — tables, task lists, strikethrough, autolinks. commonmark — without them: the string ~~text~~ will stay tildes, and | will not become a table. minimal — the same plus a picture turns into its caption.

The last is needed where the text is written by a stranger. A remote picture in a comment is a request to someone else’s server, that is, a tracking pixel and a leak of the reader’s IP; and its size the consumer does not control, and the layout of the page slides from a single line. Throwing the picture away silently would be worse: a vanished illustration leaves the reader guessing what was there. So what remains of it is its alt — as plain text in the flow.

The preset does not switch off the code block and does not touch the styling: both are the work of components and tokens.

interactiveTasks switches on the checkboxes of a task list. The taskToggle emit carries the offset of the marker in the source rather than the number of the item: matching tasks by order means missing on the very first nested list. The application rewrites the markdown by the offset and gives a new source.

The offset is correct at any nesting — an item inside an item, a list inside a quote, indentation with a tab. Where there is no footing in the source at all (a task inside a footnote definition: it is parsed outside the main flow), the checkbox stays non-interactive and there will be no emit — a number that points to the wrong place is worse than none.

They are drawn by the GrCheckbox of the core. A copy of its look of its own would diverge from the design system silently, and a native <input> is drawn by the browser itself: in the disabled state it dims in its own way and is stretched by flex into a non-square.

Without interactiveTasks the checkbox goes readonly rather than disabled: the document shows the state of the task rather than forbidding it, and the check mark stays in full colour.

The name of the checkbox is the text of its item: aria-labelledby points at the first block of the item. A shared “Task” on every one would be read out the same by a screen reader, and the tasks could not be told apart. A nested list does not enter the parent’s name — those are other tasks with names of their own. An item without text — an empty inline, a picture without a caption — is named with the translated “Task” rather than an empty name. The ids of the labels come from the instance’s useId(), so two identical documents on one page do not share them.

A task block under interactiveTasks is the only one that an edit above forces to redraw. The cache key is computed from the text, and a shifted block is recognised as the same one, while the offset of the marker is sealed into the checkbox handler: from the cache it would come from the previous source, and toggling a task would rewrite someone else’s characters. With streaming the tail is parsed separately, and the offsets of its tasks are shifted to the start of the source — taskToggle always points into the full text.

The caret slot under streaming goes inside the last inline row rather than on a line of its own below the block: that way it reads as “typing continues here” rather than as a typo. The tail is what the stream is appending right now — the last list item, the last table cell, a heading, the last block of a quote or an alert. The code block and renderers replaced through components do not take the caret: they have markup of their own, and putting someone else’s node into it is not allowed. The caret wrapper is aria-hidden: it is decorative, and a screen reader reads it neither in a paragraph nor in the name of a task.

• not an editor: the component shows and changes nothing in the source itself. Editing formatted text is GrRichText, editing markdown as code is GrCodeEditor from granularity-code;
• no code highlighting included: the code block is drawn with its own frame, language label and copying, but is not coloured. Highlighting comes through the components.code prop — your own or GrCodeBlock;
• no maths and no diagrams included: $…$ and a mermaid block stay text out of the box. Both pull in hundreds of kilobytes, and their place is in an extension — they are plugged in a section above, and the package does not pay for them;
• a frequency table of entities: the numeric forms and about forty names are expanded. A rare name will remain as written — a full table weighs more than the component itself.