Reference Live code

Annotated source

Braces in code blocks are text.

To put a value from the document into a code block, mark it live with an [!eval] comment:

mdsvex({ highlight: {} });
You write
<script>
	let install_command = 'pnpm add';
</script>

```sh
{install_command} @pkg/my-pkg # [!eval]
```

You get
Compiles to
<script>
  let install_command = 'pnpm add';
</script>

<pre
  class="twinkleplop language-sh"
  data-language="sh"><code
    ><span class="l"
      ><span class="tok"
        >{install_command}</span
      > @<span class="tok identifier"
        >pkg</span
      ><span class="tok operator"
        >/</span
      ><span class="tok identifier"
        >my</span
      ><span class="tok operator"
        >-</span
      ><span class="tok identifier"
        >pkg</span
      ></span
    ></code
  ></pre>

Every top-level {...} group on the marker's line becomes a Svelte expression, so readers see pnpm add @pkg/my-pkg. The marker itself is removed, and a line that holds only a marker is dropped.

[!eval] is a code directive, so it is written in a comment of the fence's language: // or /* */ in JavaScript, # in shell, <!-- --> in HTML and Svelte. It needs syntax highlighting, which the Vite plugin turns on by default.

On the atlas: live code.

To make one group live and leave the rest as text, name it:

You write
```js
function my_func() {
	console.log({ a: {some_val} }) // [!eval ="{some_val}"]
}
```

You get
Compiles to
<pre
  class="twinkleplop language-js"
  data-language="js"><code
    ><span class="l"
      ><span class="tok keyword"
        >function</span
      > <span class="tok function"
        >my_func</span
      ><span class="tok punctuation"
        >()</span
      > <span class="tok punctuation"
        >&#123;</span
      ></span
    >
<span class="l">	<span
        class="tok identifier"
        >console</span
      ><span class="tok punctuation"
        >.</span
      ><span class="tok function"
        >log</span
      ><span class="tok punctuation"
        >(&#123;</span
      > <span class="tok property"
        >a</span
      ><span class="tok punctuation"
        >:</span
      > <span class="tok"
        >{some_val}</span
      > <span class="tok punctuation"
        >&#125;)</span
      ></span
    >
<span class="l"
      ><span class="tok punctuation"
        >&#125;</span
      ></span
    ></code
  ></pre>

Here the outer braces stay text and {some_val} is live.

[!eval] takes the same arguments as the other code directives:

[!eval]

every top-level {...} on the marker's line

[!eval +N]

every top-level {...} on the N lines below

[!eval :N..M], [!eval :N...M]

every top-level {...} on lines N to M, exclusive or inclusive

[!eval ="{x}"]

each {x} on the marker's line

[!eval ="{x}" :*]

each {x} in the code block

[!eval a...b]

the top-level groups between the words a and b on the line

[!eval a...] and [!eval ...b]

the top-level groups from a on one line to b on a later one

A marker whose range holds no group warns.

  • Values come from the document: its <script>, and its frontmatter as metadata.
  • A value renders as text. Svelte escapes it, so markup in it shows as written. Write {@html value} to render markup.

A live group keeps the colour of the token around it, so "{base_url}/api" stays string-coloured.

  • Only expression tags, {expr} and {@html expr}. Block tags such as {#if} and {:else}, and tags such as {@const}, fail the build:
You write
```sh
{#if x}yes{/if} # [!eval]
```

Its compile throws

Error {#...} is a block tag, code can only hold {expression} and {@html expression} (line 1, column 1 of the code) (`sh` fence at /example.svx:1)

  • One line each. A group that runs onto the next line fails the build:
You write
```js
let a = {b // [!eval]
};
```

Its compile throws

Error a live expression must close on its line (line 1, column 9 of the code) (`js` fence at /example.svx:1)

  • Strings don't count. Braces inside strings and template literals in a group are skipped, so {a ? "}" : b} is one group. A group that never closes fails the build with its line and column.
  • Empty braces stay text, so {} is never live.

eval in a fence's meta means [!eval] on every line:

You write
```sh eval
{install_command} @pkg/my-pkg
{run_command} dev
```

You get
Compiles to
<pre
  class="twinkleplop language-sh"
  data-language="sh"><code
    ><span class="l"
      ><span class="tok"
        >{install_command}</span
      > @<span class="tok identifier"
        >pkg</span
      ><span class="tok operator"
        >/</span
      ><span class="tok identifier"
        >my</span
      ><span class="tok operator"
        >-</span
      ><span class="tok identifier"
        >pkg</span
      ></span
    >
<span class="l"
      ><span class="tok"
        >{run_command}</span
      > <span class="tok identifier"
        >dev</span
      ></span
    ></code
  ></pre>

It works on any fence, including languages without comments, such as json. A fence with no language takes it as its language, ```` ```eval ````.

The flag makes every top-level group in the block live. That suits commands, config and other brace-light code.

  • In JavaScript or CSS every object literal and block would become an expression, so use markers there.

A replaced pre gets the code as its code prop, with live values in place. The prop is a template literal, such as code={`${install_command} @pkg/my-pkg`}, so a copy button copies what the reader sees.

  • A custom highlighter doesn't support live code yet. A fence with the eval flag warns and its braces stay text.

mdsvex, markdown with Svelte in it. MIT licence.