Docengine

docengine.js is a simple Markdown based Javascript documentation engine. It renders <pre class="docengine"> blocks as Markdown. It also runs code blocks within these as JavaScript.

Installation

Download the library via npm:

npm install docengine

To set it up, include this in your HTML:

<link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/styles/default.min.css">

<script src="http://cdnjs.cloudflare.com/ajax/libs/marked/0.3.6/marked.min.js"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/highlight.min.js"></script>
<script src="node_modules/docengine/docengine.min.js"></script>
<script src="node_modules/docengine/uglify.min.js"></script>                <!-- required only for console mode -->

Markdown

Elements with a docengine class are converted to Markdown.

<pre class="docengine">
This is in **bold** and *italic*. Here is a [link](https://example.org/)
</pre>

Code blocks are displayed as-is.

<pre class="docengine">
Code block is highlighted as JavaScript because of the fenced block language "js".

```js
x = 100 + 200;    // This is syntax-highlighted as JS
```

Code block is highlighted as Python because of the fenced block language "python".

```python
x = 100 // 20     # This is syntax-highlighted as Python
```
</pre>

A // docengine lang:js comment on the first line sets the language to JavaScript. This helps with syntax-highlighting.

<pre class="docengine">
Code block is highlighted as JavaScript because of // docengine lang:js

    // docengine lang:js
    x = 100 + 200;    // This is syntax-highlighted as JS
</pre>

If all code blocks have the same language, use data-lang="js".

<pre class="docengine" data-lang="js">
All code blocks in this section are highlighted as JavaScript because of the `data-lang="js"`.

    x = 100 + 200;    // This is syntax-highlighted as JS

Another code block:

    y = "abc";        // This is syntax-highlighted as JS
</pre>

You can override the data-lang attribute in individual code blocks with a // docengine lang: commend or a fenced code block.

<pre class="docengine" data-lang="js">
This code block is rendered as Python. The `docengine lang:` comment overides the `data-lang` attribute.

    // docengine lang:python
    x = 100 // 20       # This is syntax-highlighted as Python

Fenced code block languages also override `data-lang`.

```python
x = 100 // 20       # This is syntax-highlighted as Python
```
</pre>

Console mode

A // docengine console comment on the first line evaluates prints the output of each JavaScript code blocks below each line. (Non-JS code blocks don't have output.)

<pre class="docengine">
In console mode, each line's result is printed below the line.

    // docengine console lang:js
    var x = 200;      // Assigns value. No result, so doesn't print anything
    x + 10;           // Prints 210
    y = {x:1, y:2}    // Prints {"x": 1, "y": 2}
    abc()             // Prints an error
</pre>

You can specify console mode for all code blocks via data-console.

<pre class="docengine" data-console>
All code blocks in this section are evaluated in DOM mode because of the `data-console` attribute.

```js
x = 100 + 200;      // Prints 300
```

Another code block that is evaluated:

    // docengine lang:js
    x = 200 + 300;    // Prints 500

Non-JS code blocks are not evaluated:

    x = 400 + 500;    // No language: Does not print anything

Here is another non-JS code block:

```python
x = 100 // 20     # Python code: coes not print anything
```
</pre>

Use // docengine none to cancel console mode for a block.

<pre class="docengine" data-console>
This code block will not be evaluated because of `// docengine none`.

    // docengine none
    x = 100 + 200;    // Does not print anything
</pre>

Use // indent:4 or data-indent="4" to indent JSON responses by 4 spaces.

<pre class="docengine" data-console data-indent="4" data-lang="js">
This output will be indented by 4 spaces:

    x = [1, 2]

This output will be indented by 8 spaces:

    // docengine indent:8
    x = [1, 2]
</pre>

DOM mode

A // docengine dom comment on the first line adds a DOM element named node just below each code block. You can add style or HTML elements to it.

<pre class="docengine">
Below this code block, a DIV element is shown with a red background and the text "This is in red".

    // docengine dom lang:js
    node.style.background = 'red'
    node.innerHTML = 'This is in red'
</pre>

By default, DIV elements are added. You can change that via // docengine dom:tag.class.

<pre class="docengine">
This code block adds an BLOCKQUOTE element with class border instead of a DIV.

    // docengine dom:blockquote.border lang:js
    node.innerHTML = 'This is a blockquote with class="border"'
</pre>

You can specify DOM mode for all code blocks via data-dom.

<pre class="docengine" data-dom data-lang="js">
All code blocks have a DIV element after them.

    node.innerHTML = 'First code block'
    node.style.background = 'lime'

Here's another code block:

    node.innerHTML = 'Second code block'
    node.style.background = 'yellow'
</pre>

You can specify a tag and class for all code blocks.

<pre class="docengine" data-dom="blockquote.border" data-lang="js">
This code block is rendered in an SVG tag with class "wide".

    node.innerHTML = 'This is a blockquote with class="border"'
</pre>

Use // docengine none to cancel DOM mode for a block.

<pre class="docengine" data-dom="blockquote.border" data-lang="js">
This code block is rendered in an SVG tag with class "wide".

    // docengine none lang:python
    node = 100 // 20    # This Python code is not evaluated
</pre>

Metadata

You can include YAML front matter at the beginning between triple-dashed lines. You must install:

npm install yaml-front-matter

This include this in your HTML:

<script src="node_modules/yaml-front-matter/dist/js-yaml-front-client.min.js"></script>

Now, YAML metadata is processed independent of the Markdown. For example:

<pre class="docengine">
---
title: Document title
date: 20 Oct 2016
---
The metadata in this block is ignored. The content (this paragraph) is rendered.
</pre>

The metadata can be pre-processed by a function specified in data-meta.

<pre class="docengine" data-meta="console.log">
---
title: Document title
date: 20 Oct 2016
---
The `data-meta="console.log"` ensures that `console.log(metadata, node)` is
called before rendering. (Check the console.)
</pre>

If the data-meta function returns a string, that string is rendered instead.

<pre class="docengine" data-console>
```js
function show_title(metadata) { return metadata.title }
```
</pre>
<pre class="docengine" data-meta="show_title">
---
title: This is the title. Only this line will be visible.
---
It doesn't matter what's here. You'll only see the title.
</pre>

If the data-meta function returns a promise, the node will be rendered with the promise's value if it's a string.

<pre class="docengine" data-console>
```js
function show_title_later(metadata) {
  return new Promise(function(resolve, reject) {
    setTimeout(function() {
      // Resolve with a string to change the output.
      // Resolve with anything other than a string to retain the output
      resolve(metadata.title)
    }, 1000)
  })
}
```
</pre>
<pre class="docengine" data-meta="show_title_later">
---
title: This is the title. Only this line will be visible -- but after 1 second
---
It doesn't matter what's here. You'll only see the title -- but after 1 second
</pre>

Callback

Once the output node is rendered, a callback function can be called.

<pre class="docengine" data-callback="console.log">
This calls `console.log(output_node)` once done
</pre>

The callback is called with the DOM element that docengine generates.

API

The script exposes a single function: docengine(el) renders el's contents as Markdown. For example:

<div id="example">
  # Heading
</div>
<script>
  docengine(document.querySelector('#example'))
</script>

... will replace #example with <div class="docengine"><h1>Heading</h1></div>. The new DOM element is returned by docengine.

You can pass a second object parameter that has the data- attributes. For example, docengine(el, {console: true, callback: method}) is the same as:

<pre class="docengine" data-console data-callback="method">

Highlighting

By default, if highlight.js is included, docengine enables syntax highlighting. To use a different style, link to one of the style themes in highlight.js.

Contributing

• This repository is hosted at https://code.gramener.com/soumya.ranjan/docengine
• Raise issues at https://code.gramener.com/soumya.ranjan/docengine/issues
• Contact [email protected] or [email protected] for queries

Release

Ensure that the common sections between this README.md and index.html have identical content.

Change the "version" string in package.json to "x.x.x", commit and tag:

git commit -m"summary of latest commit"
git tag -a vx.x.x -m"summary of all features in release"

Or, you can use npm version patch which automatically does the above. Then:

git push --follow-tags
npm publish               # as sanand0

Automated unit tests are pending.