Evalute JavaScript snippets in markdown files and output static pages.
This project will recursively traverse a folder structure searching for markdown files. Once found, it will extract javascript code blocks, evaluate them and serialise their pretty-printed output for rendering.
The tool can even automatically capture the output of your examples. See the updating section for more details.
Once the tool is installed and configured, you can point it at a config file and it will scan the specified source path and write output for matching files to a target path. The tool is invoked by:
./node_modules/.bin/evaldown --config <path_to_config>
The sections below discuss configuring the the tool and authoring you first example files.
After the package is installed, a small config file is needed which will indicate where it should read source files and target for writing output.
In its most basic form a configuration is as follows:
module.exports = {
sourcePath: "./input",
targetPath: "./output"
};
Currently the rendering process will produce HTML files as standard with
their usual .html file extension. The tool can however be requested to
output markdown files to the output directory - with the output blocks
populated - allowing its use to pre-process markdown files before they
are passed to another template engine.
"inlined"This option will write markdown files with the code and output blocks replaced with static HTML that inlines all the colouring information.
module.exports = {
outputFormat: 'inlined',
sourcePath: "./input",
targetPath: "./output"
};
"markdown"This option will write markdown files with the code and output blocks replaced with text (for use when external highlighting is desired).
module.exports = {
outputFormat: 'markdown',
sourcePath: "./input",
targetPath: "./output"
};
By default, JavaScript code blocks found in markdown files - which
we refer to as snippets - are allowed to use return statements.
The returned values will be rendered as an output block - an example
of this is shown in the authoring section below.
In some cases, rather than capture the result you may wish to capture the logging output of a command, perhaps for code that emits messages when it finished or just an example that uses the console.
Capturing from the console can be configured by adding an outputCapture
key with a value of "console" to the configuration object:
module.exports = {
outputCapture: "console",
sourcePath: "./input",
targetPath: "./output"
};
Note: changing output capturing affects all markdown files currently but will be configurable made per-snippet in future
Inside the input folder, you can make add markdown files that contain "javascript" code blocks. In order to have any output shown these need to be followed by "output" snippets.
By default, value returned from the code block is what will be captured and displayed in the
```javascript
function doSomething() {
return { foo: "bar" };
}
// objects are inspected too
return doSomething();
```
```output
```
When they are rendered, the output will look something like:
Rather than be forced to write the output by hand, we can automatially
execute the provided code snippets and inject their results into the
source markdown files. This is done using the "update" option.
As you change your examples, updating means you can always keep the output up-to-date. This mode is considered a primary use-case and can be activated by supplying an additional command line option:
./node_modules/.bin/evaldown --config <path_to_config> --update
It can also be placed within the configuration file:
module.exports = {
update: true,
sourcePath: "./input",
targetPath: "./output"
};
v0.2.0 (2020-03-29)
FAQs
Evalute JavaScript snippets in markdown files and output static pages.
The npm package evaldown receives a total of 45 weekly downloads. As such, evaldown popularity was classified as not popular.
We found that evaldown demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.