Zenn
🐀

GitHub ActionsでZennブログの校正を自動化してみた

2021/03/27に公開
2件
GitHub
Zenn
GitHub Actions
textlint
reviewdog
tech

序論

前回の記事でも紹介したとおり、ZennはGitHubリポジトリと連携すると、自分の好きなエディタで記事を書くことができます。
https://zenn.dev/yuta28/articles/first-article-by-cli-yuta

ほかにもGitHubと連携することでCIツールを導入でき、記事作成の助けにもなります。
そこで今回GitHub Actionsとtextlint、reviewdogを使いPRするたびに自動でドキュメント校正をしてくれるCI環境を構築してみました。

対象読者

  • zennでブログを書く人
  • 文章の校正の手間を減らしたい人
  • zennとGitHubが連携済み

ドキュメント校正ツール

今回GitHub Actionsに組み込む校正ツールはこちらになります。

  • textlint
  • reviewdog

textlint

textlintはMarkdownやプレーンテキスト形式のファイルを校正してくれるJavaScript製のOSSです。

https://textlint.github.io/

textlintはデフォルトルールというものが存在せず、自分でルールの設定とプラグインが必要になります。
ルールの設定箇所は.textlintrcファイル内に記述します。

.textlintrc
{
    "rules": {
        "preset-ja-technical-writing": {
            "sentence-length": false,
            "ja-no-weak-phrase": false
        },
        "prh": {
            "rulePaths": [
                "node_modules/prh/prh-rules/media/WEB+DB_PRESS.yml"
            ]
        }
    }
}

ここでは2つのルールをセットしてあります。

  • textlint-rule-preset-ja-technical-writing
  • textlint-rule-prh

textlint-rule-preset-ja-technical-writingは技術文書向けのルールプリセットです。
ルールプリセットは複数のルールを1つにまとめたルールで、textlint-rule-preset-ja-technical-writingは以下のルールが含まれています。

https://efcl.info/2016/07/13/textlint-rule-preset-ja-technical-writing/

  • 「ですます調」、「である調」を統一します
  • 同じ助詞を連続して使用しない
  • 一文の長さは90文字以下とする

ただ、文字数の縛りはURLを文中に貼るとURLの文字もカウントしてしまい、PRの承認がうまくいかないときもありましたのでfalseにしました。
ほかにも、「〜だと思います」という弱い日本語表現は技術書でしたら使わないようにしますが、ブログですのでそこまで厳しくしなくても良いと判断して、同じくfalseにしています。

textlint-rule-prhは表記ゆれをチェックしてくれる校正補助ツールです。
https://github.com/textlint-rule/textlint-rule-prh

たとえば、りんごが箱の中に有ったという文でしたら、有ったという文をあったに変換してくれます。

2021/4/10追記

Smart HRさんが新しいルールプリセットを作成して、外部に公開してくれたようです。

https://shanaiho.smarthr.co.jp/n/n881866630eda

https://github.com/kufu/textlint-rule-preset-smarthr
私の校正ルールに合いそうだと思いましたので、.textlintrcの中身を変更しました。

https://github.com/Yuhta28/zenn-blog/blob/main/.textlintrc

textlint-rule-prhの独自辞書の中身も公開してくれましたのでこちらも使ってみました。
https://github.com/kufu/textlint-rule-preset-smarthr/tree/main/dict
みなさんが使う場合は、ローカルのPCにSmart HRさんの辞書を格納しておいてください。
(私はdictディレクトリを作成してその中に置きました[1])

2023/2追記

Smart HRさんのルールプリセットですが頻繁にルールが更新され、新しいルールが投稿済みの記事の校正を行ない大量にルール検知するということがありましたので一旦取りやめました。
2023/2現在で私が利用しているtextlintのルールは以下のものを使用しています。

  • textlint-rule-preset-ja-technical-writing[2]
  • textlint-rule-prh[3]
  • textlint-filter-rule-allowlist[4]
  • textlint-rule-aws-spellcheck[5]

reviewdog

reviewdogはtextlintなどLinterツールの結果を、GitHubのPRにレビューコメントを投稿してくれるGo製のOSSです。

https://github.com/reviewdog/reviewdog

紹介した２つのツールを使うことで、ローカルで書く→git push→PRする→GtiHub Actionsが動くというCIが構築され、自動でドキュメントを校正してくれます。

それではGitHub Actionsのワークフローファイルの中身を紹介していきます。

.github/workflows/textlint.yml
# This is a basic workflow to help you get started with Actions

name: reviewdog

# Controls when the action will run. 
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  pull_request:
    branches: [ main ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  reviewdog-github-check:
    name: reviewdog (github-check)
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master

      - name: Setup Node/npm
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # キャッシュ取得
      - name: cache-node-modules
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            node-

      - name: Install textlint
        run:  'npm install --save-dev textlint textlint-rule-preset-ja-technical-writing textlint-rule-prh textlint-filter-rule-allowlist'

      # デバッグ用SSHアクション
#      - name: Setup tmate session
#        uses: mxschmitt/action-tmate@v3

      - name: Exec textlint-github-pr-check
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-review
          level: warning
          textlint_flags: "articles/**"

ワークフローファイル解説

大まかなステップの流れとしては次の通りです。

  • Nodeセットアップ
  • キャッシュ取得
  • textlintインストール
  • デバッグできるようにGitHub Actions内にSSH接続するジョブ(通常時はコメントアウト)
  • textlintの実行
  • reviewdogでPRコメントに通知

毎回のPRでNodeインストールが走ると時間がかかります。数秒程度の差ですがキャッシュを使うことで短縮できます。


キャッシュ取得前


キャッシュ取得後

2023/2更新

今まで純正のreviewdogアクションを利用していましたが、textlintとセットになったアクションを提供している人がいらっしゃいましたのでこちらを利用することにしました。

https://github.com/tsuyoshicho/action-textlint

こちらのアクションはvimのLinterツールであるVintが含まれるreviewdogアクションをベースにしたアクションで、PRへのレビュー体験が向上したものになります。
まれに純正のreviewdogアクションでtextlintの実行結果がPRコメントに通知されないことがありましたので、こちらをしばらく試してみます。

デモ実行

実際にgit pushしてdevelopブランチからmainブランチにPRし、何かしらの表現ミスがありましたら、reviewdogがこのようにレビューコメントを出してくれます。

このように、PRしてgit pushすれば自動でドキュメント校正してくれるのでデプロイ前の誤字脱字の見直し時間を減らせます。
1個前の記事[6]からリポジトリで記事を管理したので、textlintをかけてみましたが結構指摘箇所がありました。

所感

もともとCircleCI実践入門本[7]でつまずいた部分でしたが、知り合いの力を借りて何とか解決できたところです。
詳細はこちら

身近でCIを試せるものはないかと検討して、ブログ記事の自動校正化にチャレンジしてみようと思いました。
まだ記事のリポジトリ移管が進んでいませんが、移管後にドキュメント校正をしてに文章の見直しをしようと思います。

https://github.com/Yuhta28/zenn-blog

LT資料

LTのスライド資料です。

参考文献

https://gihyo.jp/book/2020/978-4-297-11411-4
https://swet.dena.com/entry/2018/09/18/142413
https://dev.classmethod.jp/articles/shuntaka-github-actions-reviewdog/
https://www.npmjs.com/package/textlint-rule-preset-smarthr
https://zenn.dev/tsuyoshicho/articles/2021-04-20-action-textv3

脚注

  1. https://github.com/Yuhta28/zenn-blog/tree/main/dict ↩︎

  2. https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing ↩︎

  3. https://github.com/textlint-rule/textlint-rule-prh ↩︎

  4. https://github.com/textlint/textlint-filter-rule-allowlist ↩︎

  5. https://github.com/37108/textlint-rule-aws-spellcheck ↩︎

  6. https://zenn.dev/yuta28/articles/first-article-by-cli-yuta ↩︎

  7. https://gihyo.jp/book/2020/978-4-297-11411-4 ↩︎

GitHubで編集を提案

Discussion

YokiYoki

こちらの記事を参考にさせて頂きましたありがとうございます🙏

GitHub Actionsにて同様な設定をした際にreviewdogによるコメントがされないのですが、何か思い当たる節ありますでしょうか？
https://github.com/yyokii/ZennContents/pull/1

ユータユータ

私の記事をご覧いただきありがとうございます。
reviewdogの仕様なのか一度の実行で大量にエラーがある場合、GitHub botにコメントがあらわれないようです。
私はデバッグ目的でRun reviewdogステップ内で直接ログの中身を見て確認できるようにしています。

cat .textlint.log

Yokiさんのワークフローファイルを確認しましたが、私と同じようにcatでログを参照していましたので、ステップの中身を確認しましたが、大量にエラーが出ていました。
エラーの出力はxml形式なので適当にメモ帳にコピーして.xml形式で保存すればエラーの中身が見れます。
https://github.com/yyokii/ZennContents/pull/1/checks

いくつかエラーを修正してもう一度pushすればreviewdogでコメントが投稿されると思いますのでお試しください。