vijithassar / rollup-plugin-markdown

import JavaScript from Markdown code blocks

Overview

This Rollup plugin lets you extract your JavaScript code from code blocks embedded in Markdown files, which in turn promotes good written documentation. This technique is called literate programming.

For a more detailed discussion about why you might want to do this, or to implement with other programming languages and other JavaScript build tools, please instead see lit, a shell script which provides the same functionality in a more agnostic fashion.

Example

GitHub Flavored Markdown represents code using fenced code blocks, which are demarcated with three backticks in a row:

function greeting() {
    console.log('hello world');
}

export { greeting };

After you import and run this plugin in your rollup.config.js configuration file, the greeting() function above can be imported directly from this Markdown document! For example, you might use the following ES6 module import statement:

import { greeting } from './path/to/README.md';

Sourcemaps will correctly point your debugging back to the original Markdown documents.

You must include js or javascript as a language specifier after opening up a fenced code block in Markdown. 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 commands.