mdz #

mdz is a small markdown dialect that supports Svelte components, auto-detected URLs prefixed with https://, /, ./, and ../, and Fuz integration like linkified identifiers and modules in `backticks`. The goal is to securely integrate markdown with the environment's capabilities, while being simple and friendly to nontechnical users.

mdz prioritizes predictability with one canonical pattern per feature, preferring false negatives over false positives to minimize surprise.

For better performance, static mdz content can be compiled at build time with svelte_preprocess_mdz.

Usage
#

import Mdz from mdz.ts:

import Mdz from '@fuzdev/fuz_ui/Mdz.svelte';

Basic formatting
#

Supports bold, italic, and strikethrough:

<Mdz content="**Bold** and _italic_ and ~strikethrough~ text." />

Bold and italic and strikethrough text.

All inline formatting can nest:

<Mdz content="**~_All_ three~ combi**_ned_" />

All three combined

Preserves whitespace
#

mdz preserves and renders all whitespace exactly as written, minimizing surprise for nontechnical users:

<Mdz content=" see how whitespace is preserved " />

see how whitespace is preserved

Line breaks and paragraphs
#

Single newlines create line breaks:

First line. Second line. Third line.

First line. Second line. Third line.

Double newlines create paragraph breaks:

First paragraph. Second paragraph. Linebreak in second paragraph.

First paragraph.

Second paragraph. Linebreak in second paragraph.

Triple newlines create paragraphs with a blank line between:

First paragraph. Second paragraph separated by an extra newline.

First paragraph.

Second paragraph separated by an extra newline.

Horizontal rules
#

Use exactly three hyphens (---) at the start of a line to create a horizontal rule. No blank lines are required around it. mdz has no setext headings, so --- after a paragraph is always an HR:

Section one. --- Section two.

Section one.

Section two.

Inline code auto-linking
#

Backtick code automatically links to identifiers and modules:

To parse markdown directly, use `mdz_parse` from module `mdz.ts`.

To parse markdown directly, use mdz_parse from module mdz.ts.

Non-identifiers become plain code elements:

This `identifier` does not exist.

This identifier does not exist.

Links
#

mdz supports four kinds of links:

  • standard markdown link syntax
  • external URLs starting with https:// or http://
  • absolute paths starting with /
  • relative paths starting with ./ or ../
[Fuz API docs](https://fuz.dev/docs/api) and https://fuz.dev/docs/api and /docs/api

Fuz API docs and https://fuz.dev/docs/api and /docs/api

Relative paths are resolved against the base prop when provided, producing correct absolute paths. Without base, they use raw hrefs (the browser resolves them against the current URL):

See ./grammar and ./spec and ../mdz for relative paths.

See ./grammar and ./spec and ../mdz for relative paths.

HTML elements
#

mdz supports an opt-in set of HTML elements for semantic markup and styling.

<aside>This is _italicized <code>code</code>_ inside an `aside`.</aside>
<marquee>use it or lose it</marquee>
use it or lose it

Elements must be registered:

import {mdz_elements_context} from '@fuzdev/fuz_ui/mdz_components.js'; mdz_elements_context.set(new Map([ ['code', true], ['aside', true], ['marquee', true], ]));

Unregistered elements render as <tag-name /> placeholders for security.

Svelte components
#

mdz supports Svelte components to a minimal (and possibly expanding) degree. Components are distinguished from HTML elements by their uppercase first letter:

<Alert>This is an `Alert` with _italicized <code>code</code>_ inside.</Alert>

Components must be registered:

import {mdz_components_context} from '@fuzdev/fuz_ui/mdz_components.js'; import Alert from '@fuzdev/fuz_ui/Alert.svelte'; mdz_components_context.set(new Map([ ['Alert', Alert], ]));

Unregistered components render as <ComponentName /> placeholders.

Advanced usage
#

For more control, use mdz_parse directly with MdzNodeView:

import {mdz_parse} from '@fuzdev/fuz_ui/mdz.js'; import MdzNodeView from '@fuzdev/fuz_ui/MdzNodeView.svelte'; const nodes = mdz_parse(content); <div class="custom white-space:pre-wrap"> {#each nodes as node} <MdzNodeView {node} /> {/each} </div>

For example you may want white-space:pre to avoid wrapping in some circumstances.

Headings
#

Use 1-6 hashes followed by a space:

#### h4 ~with~ _italic_

h4 with italic

Must start at column 0 and have a space after hashes. No blank lines are required around headings. Headings can include inline formatting.

Code blocks
#

Use three or more backticks with optional language hint:

```ts const z: number = 43; ```
const z: number = 43;

Must start at column 0 and closing fence must match opening length. No blank lines are required around code blocks.

Compatibility with other markdowns
#

mdz supports fewer syntax variants than CommonMark/GFM:

  • bold: **text** only
  • italic: _text_ only

In CommonMark, *text* is italic. In mdz, single * has no special meaning and renders as literal text. This choice creates a clear visual distinction between bold and italics.

Block elements (headings, HR, codeblocks) can interrupt paragraphs without blank lines, while inline formatting prefers false negatives over false positives. For example, ``` must have no preceding spaces or characters to start a code block.

Generated docs
#

For more see the generated mdz docs: