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

• Motivation
• Installation
• Project Status
• How does it work?
• Full Documentation
• Projects Using Specdown

The motivation for this project has from two key places, these are:

1. Documentation on GitHub projects where the documented commands and output is out of date
2. 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.