A tool to test markdown files and drive development from documentation.
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
The motivation for this project has from two key places, these are:
- Documentation on GitHub projects where the documented commands and output is out of date
- Projects which use Cucumber but no one except the developers refer to the feature files
The installation process of specdown is still in early stages. Right now you two options are to download the compiled releases from GitHub, or clone the repository and build from source. The recommended what is to download the compiled releases, you can do this from by using the following commands.
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/repo/specdown
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
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"
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 output of the previous command 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)
The documentation is written as executable specifications and can be read here.
If your project is using specdown then feel free to add it to the list.
- 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.