For a more detailed discussion about why you might want to do this, or to implement with other programming languages or without the occasional compromises made by
lit-web in pursuit of ease of use, please instead see lit, a more powerful shell script which provides the same functionality in a more agnostic fashion.
Simply load both
lit-web.js and a Markdown document containing literate programming on the page using
For example, a Markdown document named
Some HTML to serve it:
lit-web.js will load the content of
You must include
text/markdown so that
lit-web can identify which scripts are loading Markdown documents that it should process and execute. Alternatively, you can use
type attribute for
lit-web.js must instead be boring old
Loading as ES Module
Loading as a script tag is easiest, but for more stable application builds which allow dynamic execution of arbitrary Markdown you can also install from npm.
# install lit-web module$ npm install lit-web
Then you can just
import the module:
// import ES module during a build process;
In order to
import directly into a live web app over remote HTTP, you must specify the file's location and extension rather than relying on the Node.js module path resolution logic.
// import ES module remotely over HTTP;
- There are performance costs to parsing your code blocks in the client and sending the extra Markdown text content over HTTP. This should be negligible in most of the quick-and-dirty situations where a dynamic solution like
lit-webexcels. For better performance, use one of the alternative tools listed below and optimize your application build.
- It's especially important that your literate programming scripts use strict mode internally in order to cleanly avoid scope conflicts, but of course you should already be using that anyway.
- Exact line numbers reported by debugging tools may be off be a line or two relative to the original Markdown document because of the function wrapper that's added to improve scope safety.
- Only one layer of in-browser Markdown parsing is supported, so you can't use this tool to load Markdown documents with ES6
importstatements (as you can with
lit-node, for example). To
importadditional literate code files into your project, set up a build process that incorporates one of the alternative tools listed below.
- Code blocks are loaded using the Function constructor, which is sort of like a somewhat safer version of
- lit is a general-purpose source code preprocessing tool which allows you to code in a literate style in any language, and also load and interpret your Markdown documents directly
- lit-node is a wrapper for Node.js which lets Node interpret Markdown files, import modules declared inside Markdown files using
require(), and also provides a REPL
- rollup-plugin-markdown implements similar source code processing logic, but it provides more precise sourcemaps, integrates with a popular build tool, and is available via npm
- Blaze creates an agnostic local environment for literate programming in which any Markdown file can be executed
- Docco and its many variants render literate source code into beautiful browsable HTML
- CoffeeScript and Haskell support literate programming natively and do not need any additional tooling!