Directives
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.
Declaring directives
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:
export { default as img } from './Image.svelte';
export * as directives from './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 otherdirectivesexport is an error.
The three forms
An inline directive sits in a line of text. It gets its args, and the text in brackets as children:
Read the :abbr[HTML](title=HyperText) spec.<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:orstd::vectorin 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:
::youtube[A talk](id=dQw4w9WgXcQ)
::toc<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 hereis a paragraph. - A line that is only
::wordor:::wordis a directive and needs a component, write\::wordto 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:
:::Callout[Heads up](kind=warn)
Body *markdown*
:::
:::note
A note.
:::<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'.
Directive props
- Args in parentheses become string props:
(kind=warn, title="A title")giveskind="warn"andtitle="A title". Values are never Svelte expressions. labelis a snippet of the bracket text of a leaf or container. Its inline markdown is rendered, and empty or missing brackets pass nolabel.childrenis a snippet of an inline directive's bracket text, or of a container's body.
<script>
let { kind = 'note', label, children } = $props();
</script>
<aside class="callout {kind}">
{#if label}<strong>{@render label()}</strong>{/if}
{@render children?.()}
</aside>:::Callout[Heads up](kind=warn, title="A title")
Body *markdown*
:::<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
childrenis an error. So islabelon a leaf or container, though an inline directive can take alabelarg as a plain prop.
::toc(children=x)Error the directive ::toc at 1:1 has an argument named children, which its component receives as a snippet
Unknown directives
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' });# Notes
:::Calout[Heads up](kind=warn)
Body *markdown*
:::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.
Directives from a plugin
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
componentsmodule or a template replaces the plugin's component. - Two plugins can't both bring one.