Skip to main content

Convert specifications written in Markdown to ReSpec HTML

Project description

markdown-to-respec

Build Status

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/markdown-to-respec@v0.4.0

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/markdown-to-respec@v0.1.0
        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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markdown-to-respec-0.4.1.tar.gz (5.0 kB view details)

Uploaded Source

Built Distribution

markdown_to_respec-0.4.1-py3-none-any.whl (5.4 kB view details)

Uploaded Python 3

File details

Details for the file markdown-to-respec-0.4.1.tar.gz.

File metadata

  • Download URL: markdown-to-respec-0.4.1.tar.gz
  • Upload date:
  • Size: 5.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for markdown-to-respec-0.4.1.tar.gz
Algorithm Hash digest
SHA256 aada8e945723ce889a0a5404b624a6471003620906db8dbc280b6eedf1d1e873
MD5 f025f8cedc77feb28faf0953db120207
BLAKE2b-256 5efb263f39d091064f74e666bc5148f51ae872d1c07cd4bf9e82e283e8208892

See more details on using hashes here.

File details

Details for the file markdown_to_respec-0.4.1-py3-none-any.whl.

File metadata

File hashes

Hashes for markdown_to_respec-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f2e98731c5af8ab5ee46f2026fdbc2f865813343e28ffb15d1b07263d2648126
MD5 12b5a53d23aff03fa79446c0d9bb5cd5
BLAKE2b-256 61d2fe54550317b59431032d3716fa02365c9f83881dbe03889fe7d6de04639d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page