markdown_player
▶️ Executable markdown files.
Write markdown documentation, run markdown documentation!
Install
Install the CLI:
deno install --unstable -f -A -n markdown_player "https://deno.land/x/markdown_player@v1.2.2/src/bin.ts"
Install the deno
library:
import * as markdownPlayer from "https://deno.land/x/markdown_player@v1.2.2/src/mod.ts";
markdownPlayer.playFile("readme.md");
How it works
- Reads a markdown file
- Parses all fenced code blocks
- Executes each code fence in an independent or shared process
- Captures and re-emits command output!
Preview
- Write code in code blocks
- Run
markdown_player /path/to/file.md --appendOutput
- Observe the output
import { getEmojiByName } from "https://deno.land/x/getmoji@1.2.2/mod.ts";
const fileType = "markdown";
const description = `Runs code fences in a ${fileType} file`;
console.log(`${description} ${await getEmojiByName("pizza")}`);
Runs code fences in a markdown file 🍕
The above output was auto written to this document by using the --appendOutput
flag!
Features
- share execution environments between code blocks
- configure code blocks to be run with custom commands
- optionally write code blocks to files, with support for optional auto-removal
API
Code fences can be configured via single line yaml in the meta section. Consider the following markdown meta:
```bash {file: {name: greeting.sh}}
Now, apply it to a real code block (warning, the meta is hidden by real codeblocks, unless you look at the markdown source):
# creates a file called "greeting.sh"
echo "hello $USER!"
hello c1.2.2//yaml-online-parser.appspot.com/.
## Examples
### Meta blocks
The following block has meta: `` ```js {cmd: node, args: ["--eval", $ARG]} ``
```js {cmd: node, args: ["--eval", $ARG]}
// no file is written
console.log(123);
123
The following block has meta:
```js {file: {name: 456-demo.js, autoRemove: true}, cmd: node, args: [456-demo.js]}
console.log(456);
456
Share execution context
Sharing variables can be achieved by adding a {group: name}
to the codeblock
meta. All items in a group
eventually get run from a single file, where all
blocks are combined into a single file.
Math is important. Learn math! Consider this function:
const square = (x: number) => x * x;
What if we passed a two?
const twoSquared = square(2);
console.log(twoSquared);
4
What about the square of a square?
console.log(square(twoSquared));
16
Run a code block, but skip output
use the skipOutput
meta flag: ```ts {skipOutput: true}
// print out an enormous string!
console.log([...Array(1e4)].join("a\n"));
FAQ
Error: Exec format error (os error 8)
Did you try to execute a file that was not a binary, or had no
#!/usr/env/bin LANG
block?