lit-node

Load Markdown files as Node modules and run the code blocks. Self-documenting Node scripts through literate programming! Based on lit by Vijith Assar.

Overview

lit-node is a lightweight wrapper for Node.js which allows you to import code blocks from Markdown documents using the require() function. This enables first-class support for simple literate programming, a software development technique which emphasizes clear written documentation. It's sort of like Jupyter notebooks for Node. Jupyter... nodebooks? [todo: should we delete this pun? it's really stupid.]

Quick Start

# install
$ npm install lit-node

# load module from command line to enable
# execution of literate Markdown with Node
$ node --require lit-node/register program.md

# lit-node alias is just node with direct
# support for importing modules from
# Markdown code blocks
$ lit-node program.md

Instructions

First, install lit-node.

# install
$ npm install lit-node

You'll probably want a global install if you intend to use either the REPL or the alias for Node which automatically loads the lit-node module (more on these in a moment):

# install
$ npm install --global lit-node

Create a Markdown file into which to save your code and its Markdown documentation:

# create a file
$ touch test.md

Add some Markdown content to the file, including at least one code block demarcated by triple-backtick "fenced code blocks" as specified by GitHub-Flavored Markdown.

# this is a markdown file!

It can have *all the usual markdown stuff*, but only the JavaScript code blocks will run:

```javascript
// log a message
console.log('hello world');
```

Now you can execute your Markdown file!

Using the regular Node interpreter:

# execute literate Markdown files with Node,
# loading lit-node module from command line
$ node --require lit-node/register ./test.md

Alternately, the same thing using the Node alias that automatically loads the lit-node module:

# execute literate Markdown files with Node alias;
# lit-node module is automatically loaded
$ lit-node ./test.md

You must include js or javascript as a language specifier after opening up a fenced code block. Fenced code blocks that specify any other language and fenced code blocks that do not specify a language at all will be ignored. This makes it possible for you to include other code in your Markdown file without that code being executed. This is particularly useful for including Bash installation commands.

Miscellaneous

require()

Any script that has previously loaded lit-node with require() can then require() other Markdown files, which will be parsed and executed just like any other module. The .md file extension is optional, but recommended.

# load lit-node module
require('lit-node/register.js')

# scripts can load code from literate Markdown files
const thing = require('thing.md')
console.log(typeof thing)

REPL

Assuming you've installed globally as mentioned above, you can also use the Node alias installed by lit-node to launch an interactive REPL which will support Markdown imports.

# launch Node alias REPL with 
# lit-node module already loaded
$ lit-node

# the REPL can load code from literate Markdown files
> const thing = require('./thing.md');
> typeof thing

Other Tools

• IRONCLAD MONEY-BACK GUARANTEE: If you later decide literate programming in Markdown isn't for you, you can quickly and painlessly convert all your Markdown documents into regular JavaScript files by running them through lit to strip out the prose. Try it today! There is no risk!
• lit-web is a script that lets a browser execute the code blocks from a single Markdown document as JavaScript
• To interpret literate code for languages other than JavaScript, you can use either lit with subshells or Blaze, which is a drop-in replacement for usr/bin/env
• lit-node is just running Node.js internally and for a whole slew of complicated reasons Node.js doesn't yet support ES modules, so for now lit-node likewise only supports CommonJS exports. To write literate JavaScript source code using ES module syntax, either bundle with Rollup and the rollup-plugin-markdown plugin, or else process the Markdown files with lit and then do whatever else you want with other ES module tools.
• Docco and its many variants render literate source code into beautiful browsable HTML

License

LIL