Flare merges documentation and scripts and lets you run code blocks directly from your README.md. Flare is lightweight, portable and has zero dependencies beyond standard Unix/Linux tools.
Add run targets to your README.md (or another document):
## Run me
```bash [setup]{/bin/bash}
echo "Setting up environment..."
```Copy flare to your project and run commands (README.md is the default):
./flare setupKeeping documentation and project automization in sync is important for users and new developers. Flare makes it easy to avoid out-of-sync documentation and reduces redunant information by merging both into one document.
Flare acts as a command runner and is not meant to replace build tools but to make it easy to run parts of the documentation. Flare is:
- Lightweight: Flare is quite simple. It is in fact so simple that the default use case is to fork it whenever you need it.
- Portable: Works on any Unix/Linux system without additional dependencies
- Simple: Single-file implementation, easy to understand and extend
- Flexible: Supports any interpreter or build system available on your system
- Document-first: Your markdown remains readable and usable as documentation
- README-first: By default works with your project's README.md
- Permissive: Flare is licensed under CC0. Do with it as you will.
To run flare directly from command line, put flare in some location that is in your path environment variable.
If you are using bash, you can install flare by running (from within this repository):
./flare installThis executes the following script:
# Create local bin directory if it doesn't exist
mkdir -p $HOME/.local/bin/
# Copy flare to the bin directory
cp flare $HOME/.local/bin/
# Make it executable
chmod +x $HOME/.local/bin/flare
# Add to PATH (if not already there)
if ! echo $PATH | grep -q "$HOME/.local/bin"; then
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
echo "Added ~/.local/bin to PATH"
fiIf you are not using bash, you probably need to adapt updating path.
You can now run flare by running flare.
No installation needed! Just copy the flare script to your project by running this inside the project directory:
# download flare
curl -fsSL https://raw.githubusercontent.com/glor/flare/refs/heads/main/flare -o flare
# make it executable
chmod +x flareThen you can run flare locally with ./flare.
Add this to the top of your markdown file to make it directly executable:
#!/usr/bin/env -S ./flare -fThen make it executable and run it:
chmod +x README.md
./README.md # List all commands
./README.md setup # Run the setup commandThis also works with files other than README.md.
Flare uses a simple syntax to specify runnable code blocks in your markdown:
```language [command-name]{/path/to/interpreter}
your code here
```Where:
language: Markdown code block language (for syntax highlighting)[command-name]: The subcommand used to execute this block{/path/to/interpreter}: The interpreter to use (optional, defaults to/bin/sh)
Most markdown parsers and renderers remove command and interpreter so your document looks just like it used to. For end-user documentation, it is a good idea to add a code block on how to run a cell directly above.
./flare -hUsage: flare [options] [subcommand]
Options:
-f FILE Specify a markdown file to use (default: README.md)
-h Show this help message
If no subcommand is provided, lists all available subcommands in the notebook.
If a subcommand is provided, executes all code blocks tagged with that subcommand.
Examples:
flare # List commands in README.md
flare test # Run [test] blocks in README.md
flare -f notebook.md # List commands in notebook.md
flare -f notebook.md test # Run [test] blocks in notebook.md
See demo.md for a working example:
# Run with the demo file
./flare -f demo.md
# Run the test command from demo.md
./flare -f demo.md test- DevOps Documentation: Embed server setup/deployment scripts directly in documentation
- Data Science: Create reproducible research notebooks without Jupyter
- Development Workflows: Document and execute project setup tasks
- Technical Tutorials: Create fully executable technical guides
- Server Administration: Documentation that can be executed on any system without dependencies
Flare parses markdown files to find code blocks with the specified command tag. When a command is run, it:
- Extracts the code from the block
- Creates a temporary file with the code
- Executes the code with the specified interpreter
- Cleans up the temporary file
Flare is designed to be extremely portable:
- Uses POSIX-compliant shell (
/bin/sh) - Only depends on standard Unix utilities (
grep,sed,mktemp) - Works on any Unix/Linux environment without additional installations
- Can execute any script that has an available interpreter
This project is considered finished. Fixes and improvements are welcome, especially if they improve usability and portability.
This project is licensed under the CC0 License which is similar to public domain. This means that you can use flare however you'd like and without citing my name. See the LICENSE file for details.
Why "flare"? Because its like a blaze but sudden and usually brief.