• Stars
    star
    166
  • Rank 227,748 (Top 5 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 9 years ago
  • Updated about 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Test all the code in your markdown docs!

npm version Build Status Greenkeeper badge


markdown-doctest

Test all the code in your markdown docs!

Why on earth?

As an open source developer, there are few things more embarrassing than a user opening an issue to inform you that your README example is broken! With markdown-doctest, you can rest easy knowing that your example code is actually runnable.

Installation

Just npm install markdown-doctest and run markdown-doctest. It will run all of the Javascript code examples tucked away in your markdown, and let you know if any blow up.

Okay, how do I use it?

Let's try it on this repo!

var a = 5;

var b = 10;

console.log(a + c);

There's a problem with that example. markdown-doctest finds it for us:

$ markdown-doctest
x..

Failed - README.md:32:17
evalmachine.<anonymous>:7
console.log(a + c);
                ^

ReferenceError: c is not defined

Awesome! No excuse for broken documentation ever again, right? ๐Ÿ˜‰

We can also run specific files or folders by running markdown-doctest with a glob, like markdown-doctest docs/**/*.md. By default markdown-doctest will recursively run all the .md or .markdown files starting with the current directory, with the exception of the node_modules directory.

Note: markdown-doctest doesn't actually attempt to provide any guarantee that your code worked, only that it didn't explode in a horrible fashion. If you would like to use markdown-doctest for actually testing the correctness of your code, you can add some asserts to your examples.

markdown-doctest is not a replacement for your test suite. It's designed to run with your CI build and give you peace of mind that all of your examples are at least vaguely runnable.

So how do I write those examples?

In your markdown files, anything inside of code blocks with 'js' or 'es6' will be run. E.g:

```js
console.log("Yay, tests in my docs");
```

```es6
const a = 5;
console.log({a, foo: 'test'});
```

I have a code example I don't want tested!

You can tell markdown-doctest to skip examples by adding <!-- skip-example --> before the example. E.g:

<!-- skip-example -->
```js
// not a runnable example

var foo = download(...);
```

How do requires work? And other setup logic?

You can require any needed modules or example helpers in .markdown-doctest-setup.js. E.g:

// .markdown-doctest-setup.js
module.exports = {
  require: {
    Rx: require('rx')
  },

  globals: {
    $: require('jquery')
  }
}

Anything exported under require will then be used by any examples that require that key. You must explicitly configure all of the dependencies used in your examples.

Anything exported under globals will be available globally across all examples.

You can also specify a regexRequire section to handle anything more complex than an exact string match!

// .markdown-doctest-setup.js
module.exports = {
  require: {
    Rx: require('rx')
  },

  regexRequire: {
    'rx/(.*)': function (fullPath, matchedModuleName) {
      return require('./dist/' + matchedModuleName);
    }
  }
}

Do I have to enable es6 support?

Nope, ES6 support is on by default. You can disable babel support in your .markdown-doctest-setup.js file. This will speed things up drastically:

//.markdown-doctest-setup.js
module.exports = {
  babel: false
}

What if I have global state that needs to be reset after my examples run?

//.markdown-doctest-setup.js
module.exports = {
  beforeEach: function () {
    // reset your awesome global state
  }
}

You can specify a function to be run before each example in your .markdown-doctest-setup.js.

What if I want to remove custom syntax from examples before processing?

//.markdown-doctest-setup.js
module.exports = {
  transformCode(code) {
    // Remove ... from code syntax
    return code.replace(/\.\.\./g, "");
  }
}

Who uses markdown-doctest?

All of these projects either run markdown-doctest with npm test or as part of their CI process:

More Repositories

1

programmers-oath

An oath for programmers, comparable to the Hippocratic Oath
723
star
2

flask-desktop

flask-desktop lets you create first class desktop applications in Python with HTML/CSS
Python
367
star
3

sonic-pi-cli

A simple command line interface for Sonic Pi, written in Ruby
Ruby
141
star
4

cycle-restart

Swap out the code in your Cycle.js apps on the fly!
JavaScript
123
star
5

cycle-ecosystem

What are the most popular and trending libraries for Cycle.js? (curated by robots and people)
JavaScript
76
star
6

rxjs-ecosystem

What are the most popular libraries in the RxJS ecosystem?
JavaScript
66
star
7

cycle-animation-driver

A Cycle driver for requestAnimationFrame
JavaScript
34
star
8

cycle-hot-reloading-example

A Cycle.js starter project with hot reloading using browserify-hmr
JavaScript
27
star
9

tricycle

Try Cycle.js in your browser, no setup required.
JavaScript
25
star
10

stream-tree

stream-tree is a way to write functions as ASCII flowcharts in JavaScript.
JavaScript
24
star
11

rx-undoable

Easily add undo and redo to your RxJS or Cycle.js apps
JavaScript
22
star
12

hypertmux

A web powered tmux client
JavaScript
21
star
13

positron

Compile your Javascript apps to Android
JavaScript
17
star
14

recycle

cycle-restart built from the ground up for xstream
JavaScript
17
star
15

handwritten-wasm

Wasm examples, brought to you by humans!
16
star
16

cycle-collections

Moved to cyclejs/collection
JavaScript
9
star
17

cycle-music-sequencer

An easy way to make melodies in your browser, powered by Cycle.js and Tone.js
JavaScript
9
star
18

wat-shell

Replace Bash with Ruby, because why not?
Ruby
6
star
19

dotfiles

My terminal config. tmux/zsh/neovim
Vim Script
5
star
20

BushingPicker

A website to generate customized bushing setups for longboard trucks!
Python
4
star
21

bonsai-editor

JavaScript
3
star
22

cycle-carousel-example

Because a person in a youtube comment asked if it was possible
JavaScript
3
star
23

ghostwriter

An autocompleting editor for writing raps and rhymes.
JavaScript
3
star
24

cycle-dev-server

An experimental development server for Cycle.js with an inbuilt web editor
JavaScript
3
star
25

how-to-write-javascript-without-going-insane

Because it's clearly too late for me.
JavaScript
2
star
26

cycle-scripts-widdershin

My personal Cycle.js starter, for use with create-cycle-app
JavaScript
2
star
27

cycle-talk

My slides for my Cycle.js talk at Node.js Wellington
JavaScript
2
star
28

kaihoko

A shopping list that automagically buys your groceries for you.
Ruby
2
star
29

cycle-architecture-test

Testing an architecture idea for Cycle.js apps
JavaScript
2
star
30

node-line-profiler

An experimental line by line profiler for Node.js.
TypeScript
2
star
31

katana

A CLI app for code katas. Hone your mind.
Ruby
2
star
32

Tuara

Tuara is a platform aimed at connecting people with niche skills with the organizations in their community that their help could most impact.
CSS
1
star
33

randall

Discord bot used for Freestyle Fortres
Ruby
1
star
34

imagine-him-happy

Ludum Dare 50 Entry
ShaderLab
1
star
35

cho

A digital Table Tennis scoreboard
JavaScript
1
star
36

swat4-positional-audio

A Mumble plugin for SWAT 4, adding positional audio support
C++
1
star
37

Twytter

Dev Academy Week 4 Team Project - Twitter Clone
Ruby
1
star
38

talks

Any talks I give that I happen to record.
1
star
39

timestacker

Ruby
1
star
40

cycle-rest-collection

TypeScript
1
star
41

skelemation

TypeScript
1
star
42

fdbk

A space for giving and receiving feedback on your creative works
Ruby
1
star
43

cycle-pong

Pong implemented in Cycle.js, recorded as I go
JavaScript
1
star
44

something-completely-different

Stuck in a loop browsing the internet? Try something completely different.
TypeScript
1
star
45

declarate

TypeScript
1
star
46

eda-code-downloader

Download all the code you wrote at Dev Academy, I dare you!
Ruby
1
star
47

mind-your-breath

An app for mindfulness meditation
Objective-C
1
star
48

old-game-maker-games

All my old projects from when I first started coding
Game Maker Language
1
star
49

emoji-world

TypeScript
1
star
50

nzskate-search

Search all the NZ skate shops from one place!
Python
1
star
51

graphy-graph

Graphing first and second order derivatives with Cycle.js
JavaScript
1
star
52

genetic-vim-golf

Solve vim golf problems with genetic programming
JavaScript
1
star
53

workspaces

Workspaces lets you create temporary folders to work in, that can then be archived or deleted easily.
Shell
1
star