Quick Start ⚡️

Welcome to ▶️ Runme's docs

Runme makes markdown actually runnable. Runme achieves this by seamlessly loading markdown into a notebook interface which makes it much easier to complete step-by-step instructions. Let's jump right in!

💡 This document is a self-contained notebook which will guide you through Runme's key features. If you have VS Code installed locally, you can open this document in Runme by clicking the "Open with Runme" badge on docs.runme.dev which will open this document as a notebook locally. If you are already inside VS Code, you can skip over the next paragraph.

Clone the Repository

git clone --depth=1 https://github.com/stateful/docs.runme.dev.git
cd docs.runme.dev

Unless you already have VS Code installed locally, go ahead and install the Runme CLI. Otherwise skip to the next paragraph please.

MacOS

brew install runme && runme open

Linux & Windows

npx runme open

Runme by Example

Let's quickly run through examples that best illustrate how Runme can unleash your docs and make them much more useful for everybody.

🚨 Please be absolutely sure that you have cloned into the repository and opened the docs/index.md file in the notebook UI inside VS Code. Otherwise you will not be able to - literally - run the next steps.

After clicking the "Open with Runme" badge or cloning into the repo what you see should resemble following screenshot.

Generic Docs Using Prompts

Write generic docs and notebooks using Runme's smart prompting. This is useful when you want to platform others. Per default, exported environment variables will trigger prompts for users to input values. If the export is declared without any quotes, Runme will prompt with the value as a message. With quoted values (no matter if single or double quotes), Runme will prompt with the value as a placeholder value for confirmation.

Runme's prompting default is "auto". It will not prompt again on re-runs if values are already known. Click "Configure" on the cell, to switch promptEnv to no (never prompt; run as is) or yes (always prompt; overwrite previous values). Try it yourself... just click the play button.

export PROJECT_NAME=[Enter your project id]
echo "PROJECT_NAME set to $PROJECT_NAME"

export CLUSTER_ZONE="us-central1-c"
echo "CLUSTER_ZONE set to $CLUSTER_ZONE"

You can reset all environment variables using the Reset Session button in the top bar or choose "Execute and always prompt for input" from the caret menu next to the play button. Learn more here.

Piping and Referencing Cells

Runme, unlike Jupyter, does not allow block-scope variables and functions sharing. This means that variables declared in one cell are not per se available in another cell. However, Runme is aware of environment variables. As seen above, export variable declarations ulitmately will be stored in the environment.

Outside of that, you can reference cells in two ways. This is particularly useful when different languages (Bash/Shell, Python, Ruby, PHP, etc.) are used in different cells.

1. Reference Last Cell Output

The most recent cell output will be stored in a special environment variable called __ (double underscore).

ls *.md | head -n 5

This is useful when you want to reference the output of the last cell. When $__ is reference the cells have to be executed back-to-back.

echo -n "Previous cell's output was:\n\n$__"

2. Reference by Cell Name

Notice how the cell above is named FILE_LIST (visible in notebook UI & raw markdown). This allows you to reference the output of that cell by using the cell name as an environment variable. This makes reference outputs more robust since they no longer have to run back-to-back. However, sequence still matters. The referenced cells has to run first.

echo "Reference a cell via the ENV using its name \"\$FILE_LIST\":"
echo "\n$(echo -n $FILE_LIST | sort | uniq -c)"

Seamlessly Fits into DevOps Stack

Runme is 100% markdown compatible and seamlessly integrates with tooling in your DevOps stack.

Distribute ready-made Devcontainers to lock dependencies and configuration to make workflows reproducible. Runme is a perfect fit for DevOps workflows. Run docs and notebooks against SSH jumphosts or inside of popular Cloud Development Environments like GitHub Codespaces, Google IDX & Cloud Editor, Gitpod, or run as self-hosted webapp anywhere.

And so much more.

Keep going!

Learn more about Runme and what problems it solves for you.