https://github.com/r3drun3/runnable-readme

Make your readme executable! 📖 ⚙️
https://github.com/r3drun3/runnable-readme

bash documentation readme

Last synced: 10 months ago
JSON representation

Make your readme executable! 📖 ⚙️

• Host: GitHub
• URL: https://github.com/r3drun3/runnable-readme
• Owner: R3DRUN3
• License: mit
• Archived: true
• Created: 2023-01-31T07:45:48.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2023-02-01T08:07:18.000Z (over 3 years ago)
• Last Synced: 2025-04-21T10:03:11.965Z (about 1 year ago)
• Topics: bash, documentation, readme
• Language: Go
• Homepage:
• Size: 2.53 MB
• Stars: 4
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# RUNNABLE README

[![release](https://github.com/R3DRUN3/runnable-readme/actions/workflows/release.yaml/badge.svg)](https://github.com/R3DRUN3/runnable-readme/actions/workflows/release.yaml)

[![Go Report Card](https://goreportcard.com/badge/github.com/R3DRUN3/runnable-readme)](https://goreportcard.com/report/github.com/R3DRUN3/runnable-readme)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)









Make your readme executable! 📖 ⚙️




## Abstract

*Runnable Readme* is a simple utility that allows people to execute bash commands that are found in *README* (markdown) files in automatic fashion.




The advantage is twofold:

1. Allow those who follow a documentation to avoid tedious copy-paste.

2. Encourage developers to write documentation that is as clear and reproducible as possible.

We can call this *Documentation as Code* 😊

## Instructions

Download this utility from the release or clone this repo and launch it locally (it requires go v1.19).




example, clone the repo:  

```console

git clone https://github.com/r3drun3/runnable-readme.git && cd runnable-readme

```




test it against a *markdown* file:  

```console

go run main.go exec examples/example.md

```




Output:  

```console

Executing command number  1

Output: Hello World!

Executing command number  2

Output: My external IP is: 97.0.21.159

Sleeping for 3 seconds

Goodbye!

Executing command number  3

Output: where am I?

/tmp

let's create folders in loop

Sleeping for 2 seconds

removing the folders

Operation OK: true

```