examplify

Amplify your Markdown documentation with executable examples.

Introduction

examplify allows you to write Markdown documentation with executable examples.

It helps you to ensure that your examples are always in sync with executable JavaScript or presentable HTML output. You can do less work and deliver more.

If you like examplify, check out lazui at lazui.org for activating your Markdown files.

Installation

Local

npm install -g examplify

And use the file examplify.js in your project.

CDN

<script src="https://esm.sh/examplify"></script>

Usage

Before Markdown Parsing

This Markdown:

```!html
<script>console.log('Hello, World!');</script>
```

Will be turned into this:

```html
<script>console.log('Hello, World!');</script>
```
<script>console.log('Hello, World!');</script>

And this Markdown:

```!html
<form><input type="text" value="Hello, World!"></form>
```

Will actually render as this:

```html
<form><input type="text" value="Hello, World!"></form>
```

Prior to handing a string to a Markdown parser, pass it through examplify. Any code blocks marked as !html will be processed and the internals inserted immediately after the code block.

import { examplify } from 'examplify';

const string = "```!html\n<script>console.log('Hello, World!');</script>\n```";

const examplified = examplify(string);

console.log(examplified);
// => "```html\n<script>console.log('Hello, World!');</script>\n```\n<script>console.log('Hello, World!');</script>"

After Markdown Parsing

examplify will also process code blocks marked as !html after the Markdown has been parsed.

In which case, this HTML:

<code class="language-!html">
    <span class="hljs-tag">
        &lt;<span class="hljs-name">script</span>&gt;
    </span>
    <span class="language-javascript">
        <span class="hljs-variable language_">console</span>.
        <span class="hljs-title function_">log</span>
        (<span class="hljs-string">"Hello, World!"</span>)
    </span>
    <span class="hljs-tag">&lt;/
        <span class="hljs-name">script</span>&gt;
    </span>
</code>

will be converted to this:

<code class="language-!html">
    <span class="hljs-tag">
        &lt;<span class="hljs-name">script</span>&gt;
    </span>
    <span class="language-javascript">
        <span class="hljs-variable language_">console</span>.
        <span class="hljs-title function_">log</span>
        (<span class="hljs-string">"Hello, World!"</span>)
    </span>
    <span class="hljs-tag">&lt;/
        <span class="hljs-name">script</span>&gt;
    </span>
</code>
<script>console.log('Hello, World!');</script>

Pass a document object or any HTMLElement to examplify. All code blocks matching code[class*='language-!html'] will be processed. The internals will be inserted immediately after the code block as HTML and the class will be changed to language-html. Any <script> elements will be executed.

import { examplify } from 'examplify';

examplify(document);

License

MIT

Release History (reverse chronological order)

2023-10-31 v1.0.3 Ensured script elements are executing when examplify applied to DOM node.

2023-10-30 v1.0.2 Fixed bug related to two tags blocks in sequence.

2023-10-30 v1.0.1 Adjusted DOM processing to return the passed in element.

2023-10-30 v1.0.0 Added support for post-processing of Markdown.

2023-10-29 v0.0.1 Initial Release.