markdown-to-respec

markdown-to-respec is a Github Action for automatically publishing Markdown files as ReSpec HTML. The idea is that it is easier to edit and manage specifications in Markdown, but that it's easier to read specifications in your browser as HTML. By using markdown-to-respec you can have every commit to your Markdown trigger a rebuild of your HTML specifications.

As a (silly) example this Markdown file will generate this ReSpec HTML.

For the action to push to your branch you will need to grant write permission in Settings / Actions / General / Read and write permissions. Then you will need to create a .github/workflows/respec.yml file in your repository which contains:

name: Publish Specs
on:
  push:
    branches: 
      - main
jobs:
  respec:
    runs-on: ubuntu-latest
    name: Builds the ReSpec HTML
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Generate ReSpec HTML
        uses: webrecorder/[email protected]

Action Options

The action takes several options which you can specify using the with clause in your markdown-to-respec step:

• publish_branch: the branch to push the changes to (default gh-pages)
• markdown_dir: if you want to limit the processing to a particular directory (default .)

For example, to publish to another branch using an alternate build of respec_js using Markdown files in the docs directory you would:

name: Publish Specs
on:
  - push:
      branches:
        - main
jobs:
  respec:
    runs-on: ubuntu-latest
    name: Builds the ReSpec HTML
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Generate ReSpec HTML
        uses: webrecorder/[email protected]
        with:
          publish_branch: web
          markdown_dir: docs

ReSpec Configuration

ReSpec is usually configured with a JSON object in order to set authors, editors, various version URLs, etc. You have two options for these.

1. Include as frontmatter in your Markdown file: see embedded for an example.
2. Include as a JSON file along side your Markdown file: see external for an example.

If you would like to use an alternate ReSpec Javascript URL you can use the respec_js config option either in frontmatter or the external JSON configuration.

Command Line

If you want you can install markdown-to-respec and run it from the command line. This can be useful in situations where you are making local changes and want to see the resulting HTML. You should be able to use your browser to open the resulting HTML files.

usage: markdown-to-respec [-h] [--branch BRANCH] [--publish] [--ignore IGNORE] path

positional arguments:
  path             Path to search for Markdown files

options:
  -h, --help       show this help message and exit
  --branch BRANCH  Git branch to publish to
  --publish        Commit and push new HTML files
  --ignore IGNORE  A regex of Markdown files to ignore