specdown

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:

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