Guides Custom components

Source

Custom components replace the elements markdown produces. A ## heading can render your Heading.svelte, and a fenced code block your CodeBlock.svelte.

A template's <script module> exports replace elements by name, in the documents it wraps:

src/lib/templates/Docs.svelte
<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'
		}
	}
});

components names one or more modules whose exports replace elements in every document, including documents with no template:

src/lib/markdown.js
export { default as img } from './Image.svelte';
export { default as a } from './Link.svelte';
mdsvex({ components: '#lib/markdown.js' });
You write
[About](/about)

![A penguin](/penguin.png)
You get
Compiles to
<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.

For each element, mdsvex uses the first match from:

  1. the document's template, including its components override module;
  2. the components modules, the last module in the list winning;
  3. 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.

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:

elementextra props
h1 to h6level, a number from 1 to 6
ahref, title
imgsrc, alt, title, and no children
prelang, meta, code, title, caption and meta props, see code block components
codeinline code only, its text as children, and lang when it is highlighted
olstart
lichecked, true or false on a task list item (- [x] done), and no checkbox in its children
th, tdalign, "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:

src/lib/templates/docs/Heading.svelte
<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.

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'
});
You write
<a href="/about">Replaced by the a export</a>

<svelte:element this={'a'} href="/about">Never replaced</svelte:element>
You get
Compiles to
<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: or let:, 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 as onclick are plain props and are passed along.

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:

src/lib/markdown.js
export { default as warning } from './Warning.svelte';
mdsvex({ components: '#lib/markdown.js', component_mode: 'all' });
You write
<warning type="tip">

Markdown *inside* still works.

</warning>
You get
Compiles to
<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.

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:

src/lib/templates/Aside.svelte
<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>

mdsvex, markdown with Svelte in it. MIT licence.