Live code
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: {} });<script>
let install_command = 'pnpm add';
</script>
```sh
{install_command} @pkg/my-pkg # [!eval]
```
<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:
```js
function my_func() {
console.log({ a: {some_val} }) // [!eval ="{some_val}"]
}
```
<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"
>{</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"
>({</span
> <span class="tok property"
>a</span
><span class="tok punctuation"
>:</span
> <span class="tok"
>{some_val}</span
> <span class="tok punctuation"
>})</span
></span
>
<span class="l"
><span class="tok punctuation"
>}</span
></span
></code
></pre> Here the outer braces stay text and {some_val} is live.
Marker forms
[!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.
What can be live
- Values come from the document: its
<script>, and its frontmatter asmetadata. - 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:
```sh
{#if x}yes{/if} # [!eval]
```
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:
```js
let a = {b // [!eval]
};
```
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.
The eval flag
eval in a fence's meta means [!eval] on every line:
```sh eval
{install_command} @pkg/my-pkg
{run_command} dev
```
<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.
Copying live code
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
evalflag warns and its braces stay text.