Self-documenting Node scripts through literate programming
Switch branches/tags
Nothing to show
Clone or download
Latest commit e2e6606 Nov 27, 2017
Failed to load latest commit information.
test add stack trace test Nov 12, 2017
.gitignore initial commit Nov 12, 2017
LICENSE initial commit Nov 12, 2017 documentation Nov 27, 2017
compile.js d'oh Nov 14, 2017
lit-node initial commit Nov 12, 2017
package-lock.json initial commit Nov 12, 2017
register.js documentation Nov 12, 2017


Self-documenting Node scripts through literate programming. Based on lit by Vijith Assar.


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 --global lit-node

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


First, install lit-node; a global install is probably most useful:

# install
$ npm install --global lit-node

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

# create a file
$ touch

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:

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

Now you can execute your Markdown file!

$ lit-node ./

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.



From within a script being executed by lit-node, you can require() other Markdown files, which will be parsed and executed just like any other module. The .md file extension is optional.

You can do this within

// import module from a Markdown file
const thing = require('./');

// log the type of whatever was exported
console.log(typeof thing);


Assuming you've installed globally as mentioned above, you can also launch an interactive REPL which will support Markdown imports.

$ lit-node
> const thing = require('./'); // import module from a Markdown file

Top Level Await

Top-level use of await is generally a bad idea, but allowed in this case because it can be useful for short scripts.

const request = require('request-promise');
console.log(await request(''));

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