Custom components
Custom components replace the elements markdown produces. A ## heading can render your Heading.svelte, and a fenced code block your CodeBlock.svelte.
Replacing elements in a template
A template's <script module> exports replace elements by name, in the documents it wraps:
<script module>
export { default as h2 } from './docs/Heading.svelte';
export { default as pre } from './docs/CodeBlock.svelte';
</script>
<script>
let { title, children } = $props();
</script>
<main class="docs">
<h1>{title}</h1>
{@render children()}
</main>The export name is the element name. mdsvex reads the names without running the module, so export each one by name.
- A name
export *re-exports can't be seen, and mdsvex warns about it.
For a template you can't edit, such as one from a package, give the replacements in a module of their own. They are merged over the template's own:
mdsvex({
templates: {
theme: {
component: '@acme/theme/Layout.svelte',
components: '#lib/theme-overrides.js'
}
}
});The components option
components names one or more modules whose exports replace elements in every document, including documents with no template:
export { default as img } from './Image.svelte';
export { default as a } from './Link.svelte';mdsvex({ components: '#lib/markdown.js' });[About](/about)
<script>
import {
a as A_MDSVEX_G,
img as Img_MDSVEX_G,
} from '#lib/markdown.js';
</script>
<p>
<A_MDSVEX_G href="/about"
>About</A_MDSVEX_G
>
</p>
<p>
<Img_MDSVEX_G
src="/penguin.png"
alt="A penguin"
/>
</p> See the templates playground example, which uses both.
Precedence
For each element, mdsvex uses the first match from:
- the document's template, including its
componentsoverride module; - the
componentsmodules, the last module in the list winning; - no match, the plain element.
template: false documents only use the components modules.
Markdown inside a component you use, such as <Aside>, uses the same replacements as the rest of the document.
Element props
Every replacement gets the element's attributes as props, including any a parse plugin added, such as an id. Unless the element is void, it gets its content as children. Some elements get more:
| element | extra props |
|---|---|
h1 to h6 | level, a number from 1 to 6 |
a | href, title |
img | src, alt, title, and no children |
pre | lang, meta, code, title, caption and meta props, see code block components |
code | inline code only, its text as children, and lang when it is highlighted |
ol | start |
li | checked, true or false on a task list item (- [x] done), and no checkbox in its children |
th, td | align, "left", "right" or "center" |
hr and br are void too. For a fenced code block, children is the whole highlighted <pre> element.
One component can serve several elements:
<script>
let { level, id, children } = $props();
</script>
<svelte:element this={`h${level}`} {id}>
<a href="#{id}">#</a>
{@render children()}
</svelte:element>export { default as h2, default as h3 } from './docs/Heading.svelte';Svelte ignores props a component doesn't declare, so a replacement only reads what it needs.
component_mode: 'all'
By default, only elements written as markdown are replaced, so typing HTML such as <a> gets you the plain element. With component_mode: 'all', lowercase HTML you type is replaced as well:
mdsvex({
components: '#lib/markdown.js',
component_mode: 'all'
});<a href="/about">Replaced by the a export</a>
<svelte:element this={'a'} href="/about">Never replaced</svelte:element><script>
import { a as A_MDSVEX_G } from '#lib/markdown.js';
</script>
<A_MDSVEX_G href="/about"
>Replaced by the a export</A_MDSVEX_G
><svelte:element
this={'a'}
href="/about"
>Never replaced</svelte:element
> <svelte:element this={'a'}>is the escape hatch, it is never replaced.<svelte:*>elements and capitalised components are never replaced.- An element with a directive, such as
bind:,on:,use:,class:,style:,transition:,in:,out:,animate:orlet:, stays a plain element even when it has a replacement, because a component can't take a directive. mdsvex warns, naming the element and the directive. Event attributes such asonclickare plain props and are passed along.
Lowercase custom tags
With component_mode: 'all', a lowercase tag matching an export is replaced too. A warning export gives every document a <warning> tag, with no import:
export { default as warning } from './Warning.svelte';mdsvex({ components: '#lib/markdown.js', component_mode: 'all' });<warning type="tip">
Markdown *inside* still works.
</warning><script>
import { warning as Warning_MDSVEX_G } from '#lib/markdown.js';
</script>
<Warning_MDSVEX_G type="tip"
><p>
Markdown <strong>inside</strong> still
works.
</p></Warning_MDSVEX_G
> See the all mode playground example.
- A tag name that isn't a JavaScript identifier, such as
<info-box>, matches a string export:export { default as 'info-box' } from './InfoBox.svelte'. - Capitalised tags are always plain Svelte components, imported as usual.
Nested scopes
Markdown inside a component always uses the document's replacements, never ones the wrapping component supplies. Letting <Aside> change how the markdown inside it renders is deferred for now.
Until then, move that markdown into a document of its own, and give it a template with the replacements you want. Here that is an aside entry in templates, which ?template= picks on the import:
<script module>
export { default as p } from './aside/Paragraph.svelte';
</script>
<script>
let { children } = $props();
</script>
{@render children()}<script>
import AsideText from './aside-text.svx?template=aside';
</script>
## Header 2
<aside>
<AsideText />
</aside>