svelte_preprocess_mdz #

svelte_preprocess_mdz is a Svelte preprocessor that compiles static mdz content to Svelte markup at build time. Instead of parsing mdz at runtime and rendering dynamically, the preprocessor replaces the Mdz component with MdzPrecompiled containing pre-rendered children.

Setup
#

Add the preprocessor, svelte_preprocess_mdz.ts, to svelte.config.js:

import {svelte_preprocess_mdz} from '@fuzdev/fuz_ui/svelte_preprocess_mdz.js';

export default {
  preprocess: [
    svelte_preprocess_mdz({
      components: {Alert: '$lib/Alert.svelte'},
      elements: ['aside', 'details'],
    }),
    // ...other preprocessors
  ],
};

The preprocessor should run before other preprocessors like vitePreprocess() so it can parse the original Svelte source. The input to svelte_preprocess_mdz is SveltePreprocessMdzOptions.

How it works
#

The preprocessor transforms static content at build time:

<!-- Before -->
<Mdz content="**bold** and `some_fn`" />

<!-- After -->
<MdzPrecompiled><p><strong>bold</strong> and <DocsLink reference={'some_fn'} /></p></MdzPrecompiled>

For ternary expressions with static branches, it generates Svelte control flow:

<!-- Before -->
<Mdz content={show ? '**a**' : '**b**'} />

<!-- After -->
<MdzPrecompiled>{#if show}<p><strong>a</strong></p>{:else}<p><strong>b</strong></p>{/if}</MdzPrecompiled>

The preprocessor also manages imports automatically:

adds imports required by the rendered content (e.g., DocsLink, Code, resolve, configured components)
removes the Mdz import when all usages are transformed
removes dead const bindings consumed only by transformed content

What gets transformed
#

The preprocessor handles these static content patterns:

string attributes: content="**bold**"
JS string expressions: content={'**bold**'}
template literals without interpolation: content={`**bold**`}
const variable references: const msg = '**bold**'; content={msg}
ternary chains: content={show ? '**a**' : '**b**'}
nested ternaries: content={a ? 'x' : b ? 'y' : 'z'}

Relative paths and the base attribute
#

Content with relative auto-links (./grammar, ../spec) needs to know its base path to resolve those at compile time. Add a static base attribute to the Mdz tag:

<Mdz base="/docs/mdz/" content="see ./grammar and ../spec" />

The preprocessor reads base, resolves relative paths to absolute via resolve_relative_path(), and emits the resolved href values. base must be a static string literal — dynamic expressions cause the call to fall back to runtime rendering.

Without base, relative paths are kept as raw hrefs and the browser resolves them against the current URL at click time. This is a preprocessor-only attribute; at runtime Mdz accepts a base prop with the same meaning.

Skip conditions
#

The preprocessor falls back to runtime rendering when:

the file is excluded via exclude
no matching import source is found for Mdz
the import is import type (not a runtime import)
MdzPrecompiled is already imported from a different source
the content prop is dynamic (variable, function call, $state, $derived)
spread attributes are present ({...props})
content references unconfigured components or elements
a ternary branch has dynamic content or unconfigured tags