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-nodeis 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.
# 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
# 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.
// 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
require()Any script that has previously loaded
require()other Markdown files, which will be parsed and executed just like any other module. The
.mdfile 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)
REPLAssuming 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
lit-nodeis just running Node.js internally and for a whole slew of complicated reasons Node.js doesn't yet support ES modules, so for now
- Docco and its many variants render literate source code into beautiful browsable HTML