README.md

compile-mermaid-markdown-action (beta)

Purpose

Markdown is a common way to present useful information with rich formatting from a simple human readable syntax. Especially useful is being able to highlight code blocks.

Mermaid-JS takes this philosophy and applies it to graphs! Taking simple human-readable syntax and returning rich graphs.

Github markdown does not automatically render mermaid to the browser, so this action does that for you so you can just worry about the markdown and not the toolchain.

Contributing

Looking for suggestions/help in improving this action. If there is a feature you want, or you encounter a bug, please let me know and we can work together to improve it.

How to use

The idea is that this action is to be used within a workflow, not as a standalone action at this time.

Some environment variables can be set to tune the compilation:

• OUTPUT_FILE_TYPE can be used to define the output file type, if you don't specify it it will default to png. You can override it to svg or pdf.
• MMDC_EXTRA_ARGS can be used to add extra command line arguments to the mmdc command line generating diagrams. Do not include -i, -o and -p arguments as they are already handled outside of this variable.

Sample workflow with automated PR

(adapted from my example repo:

name: 'Compile Mermaid'

on:
  push:
    paths:
      - '**/*.mermaid'
      - '**/*.mmd'
      - '**/*.md'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 2
      - name: get changed files
        id: getfile
        run: |
          echo "::set-output name=files::$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} | grep -e '.*\.md$' -e '.*\.mmd$' -e '.*\.mermaid$' | xargs)"

      - name: mermaid files changed
        run: |
          echo ${{ steps.getfile.outputs.files }}

      - name: compile mermaid
        uses: neenjaw/[email protected]
        with:
          files: ${{ steps.getfile.outputs.files }}
          output: 'output'
        env:
          HIDE_CODEBLOCKS: 1
          ABSOLUTE_IMAGE_LINKS: 1
          OUTPUT_FILE_TYPE: "svg"

      - name: show changes
        run: |
          git status

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: Add compiled mermaid
          title: '[MMDC] New mermaid files compiled'
          body: |
            - Auto-generated by [create-pull-request][1]

            [1]: https://github.com/peter-evans/create-pull-request
          labels: report, automated pr
          assignees: ${{ github.actor }}
          reviewers: ${{ github.actor }}
      - name: Check outputs
        run: |
          echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}"
          echo "Pull Request Number - ${{ steps.cpr.outputs.pr_number }}"

Sample workflow with changes pushed

name: 'Compile Mermaid in Markdown'

on:
  push:
    paths:
      - '**/*.md'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 2

      - name: get changed files
        id: getfile
        run: |
          echo "::set-output name=files::$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} | grep -e '.*\.md$' | xargs)"

      - name: md files changed
        run: |
          echo ${{ steps.getfile.outputs.files }}

      - name: compile mermaid
        uses: neenjaw/[email protected]
        with:
          files: ${{ steps.getfile.outputs.files }}
          output: '.resources'
        env:
          HIDE_CODEBLOCKS: 1
          ABSOLUTE_IMAGE_LINKS: 1
          OUTPUT_FILE_TYPE: "svg"

      - name: show changes
        run: |
          git status

      - name: Commit files
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git commit -m "Add changes" -a

      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}