meld-cp_obsidian-build/docs/user-guide.md

User Guide

The Meld-Build plugin can be used to turn a note into a small, simple, runnable thing.

For example, here is a JavaScript codeblock which will display a message box with the result of a simple calculation:

```js meld-build
await $.ui.message( 56 / 5 );
```

To run it, select the Meld-Build: Run command from the command pallette.

Notice that the JavaScript codeblock above is accompanied with the text meld-build. This tells the plugin to sandbox and run the code within.

The $ accessor provides a way to use the meld-build API.

What happens when a note is run?

Within the current note:

• All tables are parsed and added to the $.data array.
• All non-meld-build blocks are added to the $.blocks array.
• JavaScript blocks with meld-build are concatenated, sandboxed and executed.

Toolbar

To make running meld-build codeblocks easier you can add the following codeblock to show a toolbar.

```meld-build-toolbar
```

TODO: add screenshot

Templating

One of the main features of meld-build is the built-in templating (provided by Handlebars).

Here is an example:

```js meld-build
const mytemplate = 'Hello {{name}}';
const mydata = { name:'World' };

const result = await $.render( mytemplate, mydata );

await $.ui.message( result );
```

There are other ways to load templates too, for example, using the content of codeblocks.

Say your note looks like this:

# My Runable Note

The template codeblock:
```html
<p>Greetings <strong>{{name}}</strong>, {{message}}</p>
```

The meld-build block to run:
```js meld-build
const template = $.blocks.at(0); // gets the first non-meld-build block in the note
const data = { name:'John', message:'How are you?' };

const result = await $.render( template, data );

await $.ui.message( result );
```

Running this note will show a message with the following text: 'Greetings John, How are you?'

See the $.io.import and $.io.load API functions for other ways to load templates.

Accessing the DataView plugin API

If you are fimilar with the DataView plugin and have it installed, you can access it's js api via the $.dv. interface.

For example:

```js meld-build
// use DataView to fetch all notes within the vault
const pages = await $.dv.pages();
... 
```

Note that the DataView rendering functions aren't supported, but you can still generate lists and tables using it's Markdown Dataviews

For example, running the following codeblock will create (or overwrite) a file named 'My List.md' with a list containing 3 items.

```js meld-build
const md = $.dv.markdownList( [1, 2, 3] );
await $.io.output( 'My List.md', md );
```

Skipping meld-build blocks

If you have multiple meld-build codeblocks in a note, you can choose to ignore some by adding skip after meld-build.

For example, running the following will display the number 0.

# My Runable Note

## code block 1
```js meld-build
let x = 0;
```

## code block 2, skipped
```js meld-build skip
x = 2;
```

## code block 3
```js meld-build
await $.ui.message(x);
```

More Information

• API
• Examples
  • Guess The Number Game
  • Simple Invoice Builder