Show and run fenced code blocks in Markdown files.
Note
I created and named this project before discovering basnijholt/markdown-code-runner. The two projects share some similarities, but the main focus of this project is to execute code blocks rather than capturing the output from the code.
bashphpshell,sh(will be run withbash)zsh
Assuming Go is installed, you can run a quick test with
go run github.com/mikkelricky/markdown-code-runner@latest showto list all code blocks in README.md in the current folder.
Install Go and install markdown-code-runner with
go install github.com/mikkelricky/markdown-code-runner@latestSee Compile and install packages and
dependencies for details on where
markdown-code-runner is actually installed.
To set things straight and clean up, it may be worth running these commands:
# Create the default installation location
mkdir -p ~/go/bin
# Clear GOBIN to use the default installation location
go env -w GOBIN=''
go install github.com/mikkelricky/markdown-code-runner@latestAdd ~/go/bin to your PATH, e.g.
# ~/.zshrc
export PATH=$PATH:$HOME/go/binSee Completions for details in how to set up completions for your terminal.
markdown-code-runner [options] [filename]If no filename is specified, input is read from stdin or README.md is used.
Show all code block (in README.md):
markdown-code-runner showShow how to run blocks:
markdown-code-runner show --verboseShow a single block:
# By name, i.e. a code block with name=coding-standards-markdown
markdown-code-runner show --verbose coding-standards-markdown
# By index
markdown-code-runner show --verbose 5Run a block:
# Run the block with name "test"
markdown-code-runner run exampleHighlight the commands being run:
markdown-code-runner run example --echo '\n👉 '(internally --echo uses PS4)
It works with both stdout and stderr:
markdown-code-runner run example-streams
# Silence stdout
markdown-code-runner run example-streams > /dev/null
# Silence stderr
markdown-code-runner run example-streams 2&> /dev/nullInteractivity also works:
markdown-code-runner run example-bash-interactiveAnd colored and styled output:
markdown-code-runner run example-bash-color"Substitutions" can be defined on a block, e.g.
```php name=example-php-substitutions substitutions='«name»: Mikkel'
<?php echo "Hello «name»!\n";
```and when the code block is run, the result will be
Hello Mikkel!Use --substitutions to substitute values, i.e. override any default substitutions, before showing or running a code
block:
markdown-code-runner show example-php-substitutions --substitutions '«name»: James'
markdown-code-runner run example-php-substitutions --substitutions '«name»: James'The substitutions must be a valid YAML mapping mapping a placeholder (e.g. «name») to a value (e.g. Mikkel). For
convenience, use Flow mappings for multiple values:
markdown-code-runner run example-php-substitutions --substitutions '{«name»: Mikkel, «number»: 87}'markdown-code-runner can automatically generate completions for four shells:
markdown-code-runner help completionLoad completions in Zsh by adding
# ~/.zshrc
eval "$(markdown-code-runner completion zsh)"; compdef _markdown-code-runner markdown-code-runnerto your ~/.zshrc. If you're cool, you do it all from the command line:
cat >> ~/.zshrc <<'EOF'
eval "$(markdown-code-runner completion zsh)"; compdef _markdown-code-runner markdown-code-runner
EOFAnd if you're even cooler, you use markdown-code-runner to run the code snippet above by its name:
markdown-code-runner run zshrc-install-completion --verbosedate
pwdecho "$0"echo "$0"echo "$0"<?php
echo PHP_VERSION, PHP_EOL;echo "This is written on stdout"
(>&2 echo "This is written on stderr")<?php
echo (new DateTimeImmutable())->format(DateTimeInterface::ATOM);<html>
<title><?php echo (new DateTimeImmutable())->format(DateTimeInterface::ATOM); ?></title>
</html><?php echo "Hello «name»!\n";task test:interactiveRED='\033[0;31m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
printf "Roses are ${RED}red${NC}. Voilets are ${BLUE}blue${NC}.\n"
for((i=16; i<256; i++)); do
printf "\e[48;5;${i}m%03d" $i;
printf '\e[0m';
[ ! $((($i - 15) % 6)) -eq 0 ] && printf ' ' || printf '\n'
done<?php echo "Hello «name»!\n";