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 soumya.ranjan@gramener.com or s.anand@gramener.com 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.