md-check

Compile and execute your markdown documentation.

Why?

1. Your docs have drifted out of sync with your codebase.
2. Your docs are incomplete or wrong and won’t compile.
3. Your users will thank you.

What?

Essentially this is like and borrows a lot from storybook and MDX. But isn’t focused on UI components.

1. Extract fences from your markdown.
2. Compile individual blocks if necessary.
3. Execute each block and optionally capture output.

This verifies that

1. Your code at the very least is valid.
2. Your code is complete including imports because each block compiles and executes by itself. No more crawling the web for what was actually imported for that random snippet that was missing pieces.
3. You code executes without an error. You could even execute tests in you code block. Part of the inspiration for this was Mocha’s doc and markdown reporters.

Install

# Run node and other commands
npm install --save-dev @btilford/md-check

# To compile typescript code blocks
npm install --save-dev @btilford/md-check-compile-typescript

Getting Started

The documentation here was generated from the markdown in examples/src by the md-check.js script .

Configure md-check

const {mdCheck, NodeVmExecutor} = require('@btilford/md-check');

const run = mdCheck({
    include: {
        patterns: [
            'docs/**/*.{md,mdx}'
        ]
    },
    executors: [
        [NodeVmExecutor.supply()]
    ]
});
// Calling run() will trigger execution.

Development

If you don’t have rush installed you’ll need to get that.

npm install -g @microsoft/rush

Clone and initialize

git clone git@github.com:btilford/md-check.git
rush install

Building

rush build