# markdown-to-respec
[](https://github.com/webrecorder/markdown-to-respec/actions/workflows/main.yml)
*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:
```yaml
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:
```yaml
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
```
[ReSpec]: https://respec.org/docs/
[Github Action]: https://docs.github.com/en/actions
[embedded]: https://raw.githubusercontent.com/webrecorder/markdown-to-respec/main/test-data/embedded/index.md
[external]: https://github.com/webrecorder/markdown-to-respec/tree/main/test-data/external
[this Markdown file]: https://raw.githubusercontent.com/webrecorder/markdown-to-respec/main/test-data/embedded/index.md
[this ReSpec HTML]: https://webrecorder.github.io/markdown-to-respec/test-data/embedded/
[configured]: https://respec.org/docs/#configuration-options
Raw data
{
"_id": null,
"home_page": "https://github.com/webrecorder/markdown-to-respec",
"name": "markdown-to-respec",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Ed Summers",
"author_email": "info@webrecorder.net",
"download_url": "https://files.pythonhosted.org/packages/5e/fb/263f39d091064f74e666bc5148f51ae872d1c07cd4bf9e82e283e8208892/markdown-to-respec-0.4.1.tar.gz",
"platform": null,
"description": "# markdown-to-respec\n\n[](https://github.com/webrecorder/markdown-to-respec/actions/workflows/main.yml)\n\n*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.\n\nAs a (silly) example [this Markdown file] will generate [this ReSpec HTML].\n\nFor 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:\n\n```yaml\nname: Publish Specs\non:\n push:\n branches: \n - main\njobs:\n respec:\n runs-on: ubuntu-latest\n name: Builds the ReSpec HTML\n steps:\n - name: Checkout\n uses: actions/checkout@v2\n - name: Generate ReSpec HTML\n uses: webrecorder/markdown-to-respec@v0.4.0\n```\n\n## Action Options\n\nThe action takes several options which you can specify using the `with` clause in your markdown-to-respec step:\n\n* `publish_branch`: the branch to push the changes to (default `gh-pages`)\n* `markdown_dir`: if you want to limit the processing to a particular directory (default `.`)\n\nFor example, to publish to another branch using an alternate build of respec_js\nusing Markdown files in the `docs` directory you would:\n\n```yaml\nname: Publish Specs\non:\n - push:\n branches:\n - main\njobs:\n respec:\n runs-on: ubuntu-latest\n name: Builds the ReSpec HTML\n steps:\n - name: Checkout\n uses: actions/checkout@v2\n - name: Generate ReSpec HTML\n uses: webrecorder/markdown-to-respec@v0.1.0\n with:\n publish_branch: web\n markdown_dir: docs\n```\n\n## ReSpec Configuration\n\nReSpec is usually [configured] with a JSON object in order to set authors, editors, various version URLs, etc. You have two options for these.\n\n1. Include as frontmatter in your Markdown file: see [embedded] for an example.\n2. Include as a JSON file along side your Markdown file: see [external] for an example.\n\nIf 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.\n\n## Command Line\n\nIf 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.\n\n```\nusage: markdown-to-respec [-h] [--branch BRANCH] [--publish] [--ignore IGNORE] path\n\npositional arguments:\n path Path to search for Markdown files\n\noptions:\n -h, --help show this help message and exit\n --branch BRANCH Git branch to publish to\n --publish Commit and push new HTML files\n --ignore IGNORE A regex of Markdown files to ignore\n```\n\n[ReSpec]: https://respec.org/docs/\n[Github Action]: https://docs.github.com/en/actions\n[embedded]: https://raw.githubusercontent.com/webrecorder/markdown-to-respec/main/test-data/embedded/index.md\n[external]: https://github.com/webrecorder/markdown-to-respec/tree/main/test-data/external\n[this Markdown file]: https://raw.githubusercontent.com/webrecorder/markdown-to-respec/main/test-data/embedded/index.md\n[this ReSpec HTML]: https://webrecorder.github.io/markdown-to-respec/test-data/embedded/\n[configured]: https://respec.org/docs/#configuration-options\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Convert specifications written in Markdown to ReSpec HTML",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/webrecorder/markdown-to-respec"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "61d2fe54550317b59431032d3716fa02365c9f83881dbe03889fe7d6de04639d",
"md5": "12b5a53d23aff03fa79446c0d9bb5cd5",
"sha256": "f2e98731c5af8ab5ee46f2026fdbc2f865813343e28ffb15d1b07263d2648126"
},
"downloads": -1,
"filename": "markdown_to_respec-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12b5a53d23aff03fa79446c0d9bb5cd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5351,
"upload_time": "2023-05-08T13:13:13",
"upload_time_iso_8601": "2023-05-08T13:13:13.158482Z",
"url": "https://files.pythonhosted.org/packages/61/d2/fe54550317b59431032d3716fa02365c9f83881dbe03889fe7d6de04639d/markdown_to_respec-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5efb263f39d091064f74e666bc5148f51ae872d1c07cd4bf9e82e283e8208892",
"md5": "f025f8cedc77feb28faf0953db120207",
"sha256": "aada8e945723ce889a0a5404b624a6471003620906db8dbc280b6eedf1d1e873"
},
"downloads": -1,
"filename": "markdown-to-respec-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "f025f8cedc77feb28faf0953db120207",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5039,
"upload_time": "2023-05-08T13:13:14",
"upload_time_iso_8601": "2023-05-08T13:13:14.292252Z",
"url": "https://files.pythonhosted.org/packages/5e/fb/263f39d091064f74e666bc5148f51ae872d1c07cd4bf9e82e283e8208892/markdown-to-respec-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-08 13:13:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "webrecorder",
"github_project": "markdown-to-respec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "markdown-to-respec"
}
JSON
