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: strict syntax with one canonical pattern per feature, preferring false negatives over false positives to minimize surprise.

Usage
#

import Mdz from mdz.ts:

import Mdz from '@ryanatkn/fuz/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. Must be separated from other content by blank lines (paragraph breaks), except at document start/end:

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 three kinds of links:

  • standard markdown link syntax
  • external URLs starting with https:// or http://
  • internal paths starting with /
[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

Note: Relative paths (./, ../) are not supported (currently, I think this will be changed). mdz content may be rendered at different URLs than where source files live (e.g., TSDoc comments from src/lib/foo.ts render at /docs/api/foo.ts). Root-relative paths (/docs/...) have unambiguous meaning regardless of render location, making them more portable. However it seems very useful to make ../ and ./ links work, maybe we can support it and make the renderer accept a custom base path?

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 '@ryanatkn/fuz/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 '@ryanatkn/fuz/mdz_components.js'; import Alert from '@ryanatkn/fuz/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 '@ryanatkn/fuz/mdz.js'; import MdzNodeView from '@ryanatkn/fuz/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, have a space after hashes, and be followed by a blank line or EOF. 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, closing fence must match opening length, and be followed by a blank line or EOF.

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.

In general, mdz wants to minimize surprise to nontechnical users, so it's strict in what it accepts and prefers false negatives over false positives. For example, it requires a separating blank line and ``` with no preceding spaces or characters to start a code block.

Generated docs
#

For more see the generated mdz docs: