Guides Directives

Source

Directives give markdown a syntax for your own components, without writing HTML. Each one renders a Svelte component:

:::Callout[Hi](kind=warn)
Body *markdown*
:::

See the directives playground example.

Directives come from a directives namespace export. Any module that can replace elements can have one, the components modules and a template's <script module> alike:

src/lib/markdown.js
export { default as img } from './Image.svelte';
export * as directives from './directives.js';
src/lib/directives.js
export { default as Callout } from './Callout.svelte';
export { default as youtube } from './YouTube.svelte';
export { default as abbr } from './Abbr.svelte';
export { default as toc } from './Toc.svelte';
export { default as note } from './Note.svelte';
mdsvex({ components: '#lib/markdown.js' });

A directive's name matches an export name exactly, so :::Callout uses Callout. Directives and elements are separate, so a table directive never replaces tables, and an element export never serves a directive.

A template's directives come before those of the components modules, in the same order as element replacements.

  • Write it as export * as directives from '...', so mdsvex can read the names without running the module. Any other directives export is an error.

An inline directive sits in a line of text. It gets its args, and the text in brackets as children:

You write
Read the :abbr[HTML](title=HyperText) spec.
You get
Compiles to
<script>
  import { abbr as Abbr_MDSVEX_D_G } from '#lib/directives.js';
</script>

<p>
  Read the <Abbr_MDSVEX_D_G
    title="HyperText"
    >HTML</Abbr_MDSVEX_D_G
  > spec.
</p>
  • An inline directive always needs its brackets, which can be empty: :icon[]. Without them a :tada: or std::vector in a sentence would be a directive.

A leaf takes a line of its own. It gets its args, and the text in brackets as label:

You write
::youtube[A talk](id=dQw4w9WgXcQ)

::toc
You get
Compiles to
<script>
  import {
    youtube as Youtube_MDSVEX_D_G,
    toc as Toc_MDSVEX_D_G,
  } from '#lib/directives.js';
</script>

<Youtube_MDSVEX_D_G id="dQw4w9WgXcQ"
  >{#snippet label()}A talk{/snippet}</Youtube_MDSVEX_D_G
><Toc_MDSVEX_D_G />

Its brackets are optional: ::toc is the same as ::toc[], and args can follow the name directly, as in ::toc(depth=2).

  • Nothing else can follow on the line, so ::toc is here is a paragraph.
  • A line that is only ::word or :::word is a directive and needs a component, write \::word to keep it as text.

A container takes a line of its own too, and ends at a line of colons. It gets its args, the text in brackets as label and the body as children:

You write
:::Callout[Heads up](kind=warn)
Body *markdown*
:::

:::note
A note.
:::
You get
Compiles to
<script>
  import {
    Callout as Callout_MDSVEX_D_G,
    note as Note_MDSVEX_D_G,
  } from '#lib/directives.js';
</script>

<Callout_MDSVEX_D_G kind="warn"
  >{#snippet label()}Heads up{/snippet}
  <p>Body <strong>markdown</strong></p>
</Callout_MDSVEX_D_G><Note_MDSVEX_D_G>
  <p>A note.</p>
</Note_MDSVEX_D_G>

Containers nest when the outer one uses more colons. Its brackets are optional, as a leaf's are.

The bracket text can hold emphasis, strong, code and other directives, but links and images in it stay plain text.

A name starts with a letter, then letters, digits, _ or -. A name that isn't a JavaScript identifier, such as info-box, matches a string export: export { default as 'info-box' } from './InfoBox.svelte'.

  • Args in parentheses become string props: (kind=warn, title="A title") gives kind="warn" and title="A title". Values are never Svelte expressions.
  • label is a snippet of the bracket text of a leaf or container. Its inline markdown is rendered, and empty or missing brackets pass no label.
  • children is a snippet of an inline directive's bracket text, or of a container's body.
src/lib/Callout.svelte
<script>
	let { kind = 'note', label, children } = $props();
</script>

<aside class="callout {kind}">
	{#if label}<strong>{@render label()}</strong>{/if}
	{@render children?.()}
</aside>
You write
:::Callout[Heads up](kind=warn, title="A title")
Body *markdown*
:::
You get
Compiles to
<script>
  import { Callout as Callout_MDSVEX_D_G } from '#lib/directives.js';
</script>

<Callout_MDSVEX_D_G
  kind="warn"
  title="A title"
  >{#snippet label()}Heads up{/snippet}
  <p>Body <strong>markdown</strong></p>
</Callout_MDSVEX_D_G>
  • An arg named children is an error. So is label on a leaf or container, though an inline directive can take a label arg as a plain prop.
You write
::toc(children=x)
Its compile throws

Error the directive ::toc at 1:1 has an argument named children, which its component receives as a snippet

A directive with no component is an error that names it and its line and column. With the modules above as the components:

mdsvex({ components: '#lib/markdown.js' });
You write
# Notes

:::Calout[Heads up](kind=warn)
Body *markdown*
:::
Its compile throws

Error no component renders the directive :::Calout at 3:1. Export a component named "Calout" from a directives module (export * as directives from './directives.ts'), or replace the directive_container node in a parse plugin

A parse plugin can handle directives that have no component, through the directive_inline, directive_leaf and directive_container node types. A directive with a component never reaches those handlers, a plugin reads it by observing it.

A plugin can bring directives of its own, with the components that render them.

@mdsvex/plugin-steps is one.

  • They sit below everything above: an export of the same name from a components module or a template replaces the plugin's component.
  • Two plugins can't both bring one.

mdsvex, markdown with Svelte in it. MIT licence.