[BLIND] Docs CI（markdownlint + Mermaid lint + reviewdog）を導入する

[LevelCapTech]

[BLIND] Docs CI（markdownlint + Mermaid lint + reviewdog）を導入する

依頼の要点

リポジトリの Markdown ドキュメント品質を維持するため
Docs CI を GitHub Actions に導入する。

導入する CI

1. markdownlint CI
2. Mermaid lint CI

Markdown lint と Mermaid lint の結果は
reviewdog により PR コメントとして表示する。

Mermaid 図は Markdown 内に埋め込まれているため
Markdown から Mermaid ブロックを自動抽出し構文検証する。

本 Issue は BLIND Issue として作成されており
本文のみで CI を実装できる。

---

対象 Markdown

/doc/**/*.md
/.github/**/*.md

---

作成する workflow

.github/workflows/markdownlint.yml
.github/workflows/mermaid-lint.yml

---

1 Markdown Lint CI

目的

Markdown lint を CI に導入する。

lint 結果は reviewdog により PR コメントとして表示する。

---

workflow

.github/workflows/markdownlint.yml

実装例（そのまま使用可能）

name: markdownlint

on:
  pull_request:
    paths:
      - "doc/**/*.md"
      - ".github/**/*.md"
  push:
    paths:
      - "doc/**/*.md"
      - ".github/**/*.md"

jobs:
  markdownlint:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install tools
        run: |
          npm install -g markdownlint-cli
          npm install -g reviewdog

      - name: Markdown lint
        run: |
          markdownlint "doc/**/*.md" ".github/**/*.md" \
          | reviewdog \
            -f=markdownlint \
            -name="Markdownチェック" \
            -reporter=github-pr-review \
            -level=warning

---

markdownlint 設定

作成ファイル

.markdownlint.json

内容

{
  "MD013": false,
  "MD033": false
}

理由

Rule	理由
MD013	Mermaid 図で長行が発生
MD033	HTMLタグ使用許可

---

2 Mermaid Lint CI

目的

Markdown 内 Mermaid 図の構文エラーを CI で検出する。

処理フロー

1 Markdown を取得
2 Mermaid block を抽出
3 .mmd ファイル生成
4 mermaid-cli で検証
5 reviewdog で PR コメント

---

Mermaid block 例

```mermaid
flowchart TD
A --> B
```

---

Mermaid workflow

.github/workflows/mermaid-lint.yml

---

実装例（そのまま使用可能）

name: mermaid-lint

on:
  pull_request:
    paths:
      - "doc/**/*.md"
      - ".github/**/*.md"

jobs:
  mermaid:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install tools
        run: |
          npm install -g @mermaid-js/mermaid-cli
          npm install -g reviewdog

      - name: Extract Mermaid blocks
        run: |
          mkdir -p tmp
          node <<'EOF'
          const fs = require('fs')
          const path = require('path')

          let i = 0

          function walk(dir) {
            if (!fs.existsSync(dir)) return
            fs.readdirSync(dir).forEach(file => {
              const full = path.join(dir, file)
              if (fs.statSync(full).isDirectory()) walk(full)
              else if (full.endsWith('.md')) processFile(full)
            })
          }

          function processFile(file) {
            const lines = fs.readFileSync(file, 'utf8').split('\n')
            let inside = false
            let buffer = []
            let startLine = 0

            lines.forEach((line, idx) => {
              if (line.startsWith("```mermaid")) {
                inside = true
                buffer = []
                startLine = idx + 1
                return
              }

              if (inside && line.startsWith("```")) {
                inside = false
                const name = `tmp/diagram-${++i}.mmd`
                fs.writeFileSync(name, buffer.join('\n'))
                fs.appendFileSync("tmp/map.txt", `${name}:${file}:${startLine}\n`)
                return
              }

              if (inside) buffer.push(line)
            })
          }

          walk("doc")
          walk(".github")
          EOF

      - name: Validate Mermaid diagrams
        run: |
          touch result.txt

          while IFS=":" read -r mmd src line; do
            if ! mmdc -i "$mmd" -o "$mmd.svg"; then
              echo "$src:$line: Mermaid図の構文エラー" >> result.txt
            fi
          done < tmp/map.txt

      - name: Report via reviewdog
        run: |
          cat result.txt | reviewdog \
            -efm="%f:%l: %m" \
            -name="Mermaid図チェック" \
            -reporter=github-pr-review \
            -level=error

---

Mermaid CI フロー

flowchart TD

A[Markdown files]
B[extract mermaid blocks]
C[generate mmd files]
D[mermaid-cli render]
E[reviewdog comment]

A --> B
B --> C
C --> D
D --> E

Loading

---

reviewdog コメント例

PR に次のようなコメントが表示される。

Mermaid図チェック

doc/architecture.md:42
Mermaid図の構文エラー

---

変更可能範囲

変更可

.github/workflows/*
.markdownlint.json

変更禁止

アプリケーションコード

---

ローカル確認

Markdown lint

npx markdownlint "doc/**/*.md" ".github/**/*.md"

Mermaid

mmdc -i diagram.mmd -o diagram.svg

---

Done

以下を満たすこと。

• markdownlint CI が動作
• lint 結果が reviewdog PR コメントで表示
• Mermaid lint CI が動作
• Mermaid block が自動抽出される
• Mermaid 構文エラーが PR コメントされる
• CI が成功する