Convert specifications written in Markdown to ReSpec HTML
Project description
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/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 (defaultgh-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.
- Include as frontmatter in your Markdown file: see embedded for an example.
- 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for markdown_to_respec-0.4.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f2e98731c5af8ab5ee46f2026fdbc2f865813343e28ffb15d1b07263d2648126 |
|
MD5 | 12b5a53d23aff03fa79446c0d9bb5cd5 |
|
BLAKE2b-256 | 61d2fe54550317b59431032d3716fa02365c9f83881dbe03889fe7d6de04639d |