# Interesting trend of executable markdown readme projects (Syntax comparison)

**URL:** <https://talk.commonmark.org/t/interesting-trend-of-executable-markdown-readme-projects-syntax-comparison/4577>\
**Category:** Uncategorized\
**Created:** [January 11, 2024, 1:56pm UTC](https://talk.commonmark.org/t/interesting-trend-of-executable-markdown-readme-projects-syntax-comparison/4577 "2024-01-11T13:56:19Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![mofosyne](https://talk.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [January 11, 2024, 1:56pm UTC](https://talk.commonmark.org/t/interesting-trend-of-executable-markdown-readme-projects-syntax-comparison/4577/1 "2024-01-11T13:56:19Z")

</div>

Just noticed there is a whole bunch of projects focusing on executable readmes.

Can you remind me what’s the common consensus on attributes for code blocks?  
I think Runme has the closest form to what was discussed regarding consistent attribute syntax.

Anyway it may be of interest to everyone here on the different styles floating around regarding executable code blocks.

The two common applications seen so far below is:

- Command Runners similar in purpose to [GitHub - casey/just: 🤖 Just a command runner · GitHub](https://github.com/casey/just) but is blended into markdown documents
- Self verifying calculations in markdown documents

## Runme

> **[GitHub - runmedev/runme: DevOps Notebooks Built with Markdown](https://github.com/runmedev/runme)**
>
> DevOps Notebooks Built with Markdown

This is for executable rundocs. In a sense, this is similar to `justfile` and Pryrite

````
# My Project

## Install

To initiate the installation process, start by updating Brew dependencies with the following command:

```sh { name=update-brew }
brew update
...
```

````

## Pyrite

> **[GitHub - 1xyz/pryrite: Pryrite, interactively execute shell code blocks...](https://github.com/1xyz/pryrite)**
>
> Pryrite, interactively execute shell code blocks in a markdown file

Pryrite, interactively execute shell code blocks in a markdown file. So this is similar to runme

````
# Hello world

Lets try some examples

* Hello world

```shell
echo "Hello world"
```

* Try a command with some output, say list files in this directory

```shell
ls -l
```

* How about setting a variable and using it later
```shell
TMPDIR=/tmp/
```

* List TMPDIR
```shell
ls -l $TMPDIR
```

* Running sudo
```shell
sudo whoami
```

````

## RunMD

> **[GitHub - broofa/runmd: Executable markdown files](https://github.com/broofa/runmd)**
>
> Executable markdown files

This focuse on running code snippet and rendering output

````
```javascript --run
const foo = 'def';
```

```javascript --run alpha
const foo = 'alpha';
```

```javascript --run beta
const foo = 'beta';
```

````

## Markdown Code Runner

> **[GitHub - basnijholt/markdown-code-runner: Automatically execute code blocks within a...](https://github.com/basnijholt/markdown-code-runner)**
>
> Automatically execute code blocks within a Markdown file and update the output in-place

Python package that runs code blocks and updates the output in-place

```
This is an example code block:

<!-- CODE:START -->
<!-- print('Hello, world!') -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
This content will be replaced by the output of the code block above.
<!-- OUTPUT:END -->

```

## Markdown Exec

> **[GitHub - pawamoy/markdown-exec: Utilities to execute code blocks in Markdown...](https://github.com/pawamoy/markdown-exec)**
>
> Utilities to execute code blocks in Markdown files.

Utilities to execute code blocks in Markdown files. For example, you write a Python code block that computes some HTML, and this HTML is injected in place of the code block.

````
```python exec="on"
print("Hello Markdown!")
```

````

---

<div class="post-metadata">

**Author:** ![samwilson](https://talk.commonmark.org/user_avatar/talk.commonmark.org/samwilson/32/2331_2.png) [@samwilson](https://talk.commonmark.org/u/samwilson)\
**Post date:** [January 12, 2024, 2:58am UTC](https://talk.commonmark.org/t/interesting-trend-of-executable-markdown-readme-projects-syntax-comparison/4577/2 "2024-01-12T02:58:52Z")

</div>

Another one is Phabricator/Phorge’s [remarkup](https://we.phorge.it/book/phorge/article/remarkup/), which uses comma separated pairs that can be valueless, e.g.:

````
```lang=html, name=example.html, lines=12, counterexample
foo
```

````

---

<div class="post-metadata">

**Author:** ![JohnZabroski](https://talk.commonmark.org/user_avatar/talk.commonmark.org/johnzabroski/32/3518_2.png) [@JohnZabroski](https://talk.commonmark.org/u/JohnZabroski)\
**Post date:** [August 28, 2026, 4:48pm UTC](https://talk.commonmark.org/t/interesting-trend-of-executable-markdown-readme-projects-syntax-comparison/4577/3 "2026-08-28T16:48:38Z")

</div>

This is basically how Microsoft Docs already works. Many of the examples are “linked” into the markdown as Self-Contained, Correct, Compilable Examples (SCCCE).  
Also, in .NET (since your survey under-represents my homeland :-)), there is Simon Cropp’s [GitHub - SimonCropp/MarkdownSnippets: Extracts snippets from code files and merges them into markdown documents. · GitHub](https://github.com/SimonCropp/MarkdownSnippets), which was in-turn inspired by [GitHub - shiftkey/scribble: Making documentation for .NET projects easy and fun · GitHub](https://github.com/shiftkey/scribble) (13 years old).