markdown-to-respec

markdown-to-respec 是一个用于自动将Markdown文件发布为 ReSpec HTML的 GitHub Action。其理念是，在Markdown中编辑和管理规范更容易，但在浏览器中以HTML阅读规范更容易。通过使用 markdown-to-respec，您可以每次提交Markdown文件时都触发HTML规范的重建。

作为一个（愚蠢的）示例，这个Markdown文件将生成这个ReSpec HTML。

要使操作推送到您的分支，您需要在设置 / 操作 / 通用 / 读取和写入权限中授予写权限。然后您需要在您的存储库中创建一个.github/workflows/respec.yml文件，它包含

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

操作选项

该操作接受几个选项，您可以使用markdown-to-respec步骤中的with子句来指定这些选项

• publish_branch：要推送更改的分支（默认 gh-pages）
• markdown_dir：如果您想限制处理特定目录（默认 .）

例如，要使用docs目录中的Markdown文件使用替代的respec_js构建发布到另一个分支，您将

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 配置

ReSpec 通常通过在JSON对象中配置来设置作者、编辑、各种版本URL等。您有两个选择。

1. 作为Markdown文件的前置元数据包含：请参阅嵌入式示例。
2. 作为与Markdown文件并列的JSON文件包含：请参阅外部示例。

如果您想使用替代的ReSpec JavaScript URL，您可以使用respec_js配置选项，在前置元数据或外部JSON配置中。

命令行

如果您愿意，可以安装 markdown-to-respec 并从命令行运行它。这在您进行本地更改并希望查看结果 HTML 时非常有用。您应该能够使用浏览器打开生成的 HTML 文件。

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