markcheck

Markcheck

• Markcheck tests Markdown code blocks – to prevent errors in documentation (readmes, blogs, books, etc.).
• Name of npm package: markcheck

Why Markcheck?

Highlights:

• Uses normal Markdown syntax – not a custom version of it: Everything custom happens inside Markdown comments.

• No external files: The Markdown file contains all the information that is needed to run it: Configuration files, demo text files, etc. can all be embedded in Markdown.

  • Exception: Some data remains external – e.g. npm packages used by JavaScript code.

• Works for most programming languages: The only requirement is that there is a shell command that runs text files with the language’s code. See demo/demo-bash.md for an example of testing a programming language that Markcheck has no built-in support for.

• Successfully used in a big project: I tested almost all of the code shown in my book “Exploring JavaScript”. Its PDF has 687 pages.

• Provides versatile tools for checking code: Human readers of the published Markdown never see the complexity that is occasionally needed to make code blocks testable. These are some of the tools at our disposal – they can all be used from within Markdown files:

  • Check stderr and/or stdout.
  • Concatenate code blocks in any order.
  • Use code hidden from readers.
  • Write arbitrary text files to disk (example files, config files, etc.).
  • Etc.

Checking JavaScript is reasonably fast:

• Checking all the examples in “Exploring JavaScript” takes 50 seconds on a MacBook Pro with an M1 Pro processor. There is a lot of code in this book.
• Checking one of the longer chapters takes 5 seconds.

Caveats:

• Only tested on macOS. I used cross-platform mechanisms where I could but I don’t know if Markcheck works on Windows. Please let me know either way.
• ⚠️ There is currently no sandboxing of any kind: Only use Markcheck with files you trust.
• Checking TypeScript code:
  • Downside: slow
  • Upside: You can write very expressive code that works well for explaining language mechanisms. See demo/demo-typescript.md for more information.

What does Markcheck’s syntax look like?

The following subsections contain three examples. For more examples, see the quick start part of Markcheck’s manual.

Checking basic code blocks

```js
assert.equal(
  'abc' + 'abc',
  'abcabc'
);
```

No additional configuration is needed: The Node.js assert.* methods are available by default.

Checking standard output via stdout

```js
console.log('Hello!');
```

<!--markcheck define="stdout"-->
```
Hello!
```

Hiding code via before:

<!--markcheck before:
function functionThatShouldThrow() {
  throw new Error();
}
-->
```js
try {
  functionThatShouldThrow();
  assert.fail();
} catch (_) {
  // Success
}
```

More information on Markcheck

• Demo files with code blocks in these languages: JavaScript, TypeScript, Babel, Node.js REPL, Bash
• Quick start with many examples
• Manual

Donations

I have rewritten Markcheck several times over the years, until I arrived at the current version. If you find this tool or any of my other free work useful, I would appreciate a donation:

• One-time donation:
  • Paypal
  • Stripe
• Recurring donations:
  • GitHub Sponsors
  • Liberapay