- Use case: Blog posts and books, not documentation for software.
- As much code as possible should be included within the Markdown file.
- I’m currently using
§
as a meta-character.- I’m open to alternatives. Other characters I considered:
¡ ¿ Δ ≡
- I wanted it to be a non-ASCII character, to minimize the risk of conflicts.
- I’m open to alternatives. Other characters I considered:
JavaScript to be checked:
<!--§check-->
```js
Math.hypot(3, 4); //→ 5
```
Code that isn’t syntactically legal:
```js
class Foo {
constructor(name) {
this.name = name;
}
···
}
```
markdown-doctest is currently opt out only. Every example is run by default, need to prepend
<!-- skip-example -->
to skip a code block. This means adoption is easier, as usually the majority of code blocks are runnable, and new code blocks should not require the user to opt in.
<!--§id:point-->
```js
class Point {
constructor(x, y) {
this.x = x;
this.y = y;
}
}
```
<!--§include:point-->
```js
const point = new Point(5, 2);
```
markdown-doctest doesn't currently support includes like this, but could without too much work.
Without ID: add to following code block.
<!--§js:
import {foo} from 'bar';
-->
```js
foo();
```
With ID: defines a named code block.
<!--§js:the-imports
import {foo} from 'bar';
-->
<!--§include:the-imports-->
```js
foo();
```
markdown-doctest doesn't currently support javascript in comments, but it's a good idea. Currently you would achieve this by adding
foo
to the globals object in your markdown doctest configuration.
```js
console.log(3 + 4); //→ 7
function add(x, y) {
return x + y;
}
add(3, 4); //→ 7
```
```js
const obj = {
foo: 1,
bar: 2,
};
for (const [k,v] of Object.entries(obj)) {
console.log(k, v); //→
}
// Output:
// 'foo' 1
// 'bar' 2
```
markdown-doctest doesn't support checks like this, and they're actually quite complex to implement and support. There are a whole bunch of special cases that can be very brutal to support or workaround. My recommendation is to include assert calls in your examples when you want checks like this.
```repl
> const x = 3;
> const y = 4;
> x + y
7
```
- Once, at the end of a file. Is used for the whole file.
- Always:
babel-preset-env
(means all latest features) - Explicitly: experimental plugins
<!--§babel:
{
"plugins": ["transform-react-jsx"]
}
-->
this is achieved in the markdown-doctest config
- Also lint the code?
For REPL blocks, I’d transform:
into: