Self-documenting Node scripts through literate programming
npm install lit-nodeLoad Markdown files as Node modules and run the code blocks. 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.]
``bashinstall
$ npm install lit-node
Instructions
First, install
.`bash
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):
bash
install
$ npm install --global lit-node
`Create a Markdown file into which to save your code and its Markdown documentation:
bash
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:
bash
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:
bash
execute literate Markdown files with Node alias;
lit-node module is automatically loaded
$ lit-node ./test.md
`You must include
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
$3
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.`javascript
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)
`$3
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.
bash
launch Node alias REPL with
lit-node module already loaded
$ lit-nodethe 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
- 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.