A tool to test markdown files and drive development from documentation.
This document is an executable specification
When SpecDown is run with this document, it will execute the following shell command:
echo "Hello SpecDown"
It will then validate that the output from the above command matches the following codeblock:
Hello SpecDown
Table Of Contents
Motivation
The motivation for this project has come from two key places, these are:
- Documentation on GitHub projects where the documented commands and output are out of date
- Projects which use Cucumber but no one except the developers refer to the feature files
Installation
Currently, your three options are downloading the compiled releases from GitHub, using Homebrew, or cloning the repository and building from the source. The recommended way is to download the compiled releases; you can do this by using the following commands.
Mac OS
You can download the binary and add it to your path:
curl -L https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-apple-darwin -o /usr/local/bin/specdown
chmod +x /usr/local/bin/specdown
Alternatively, you can also use brew
brew install specdown/homebrew-repo/specdown
Linux
You can download the binary and add it to your path:
curl -L https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-unknown-linux-gnu -o /usr/local/bin/specdown
chmod +x /usr/local/bin/specdown
You can also use Homebrew on Linux to install the application
brew install specdown/repo/specdown
Windows
You can download the binary and add it to your path:
Invoke-WebRequest -Uri "https://github.com/specdown/specdown/releases/latest/download/specdown-x86_64-pc-windows-msvc.exe" -OutFile "specdown.exe"
How does it work?
The markdown for the example at the beginning of this document looks like this.
Let’s save it to a file called example.md
:
## This document is an executable specification
When SpecDown is run with this document, it will execute the following shell script.
```shell,script(name="hello-specdown")
echo "Hello SpecDown"
```
It will then validate that the previous command's output matches the following codeblock.
```,verify(script_name="hello-specdown", stream=stdout)
Hello SpecDown
```
You can run this markdown specification by using the following command:
specdown run example.md
This will produce the following output:
Running tests for example.md:
✓ running script 'hello-specdown' succeeded
✓ verifying stdout from 'hello-specdown' succeeded
2 functions run (2 succeeded / 0 failed)
Full Documentation
The documentation is written as executable specifications and can be read here.
Projects Using Specdown
If your project is using specdown then feel free to add it to the list.
- carbon-guard
A unique and environmentally conscious GitHub Action & CLI App designed to help reduce the carbon footprint of your CI/CD pipelines. - ed-system-search
A tool to find interesting systems in Elite: Dangerous. - ellipsis
A dotfile manager. - git-mit
A suite of git hooks. It’s aimed to make pair programming, adding issue numbers to your commits, and following good commit message practices something that happens without thinking about it. - specdown
Specdown tests itself. - whatismyip
Work out what your external ip is.