【textlint】を使って職務経歴やマークダウンを読みやすくする

概要

textlintというツールを使って、読みやすい文章にしつつ、職務経歴をまとめたかった。ネットでいくつか記事を見つけたものの、一度ローカルにtextlintをインストールし、それをGitへプッシュするやり方の解説しか見つけることができなかった。私は、ローカル環境を汚したくなく、ローカルにインストールするのを避けたかったので、全てGithub Actionsで実行することとした。

ローカルにインストールすることを前提にした解説しか見つけられず、設定の仕方等で躓きまくったので、備忘として記事に残す。

（※今回作成した職務経歴書を管理しているリポジトリは、具体クライアント名などを入れてしまっているため、リポジトリは非公開としています。）

textlintの使い方

フォルダ構成

./
┗.github/
  workflows/
    github_actions.yml # Github Actionsのジョブ実行フローを定義するためのファイル。ファイル名は何でもOK
┗docs/
	┗書類1.md
	┗書類2.md
┗.textlintrc.json # textlintを利用するための設定ファイル。ファイル名はコレにしないといけない。厳密にはそうではないが。

Github Actionsワークフローの定義

github_actions.yml

name: lint

on:
  pull_request:
    branches:
      - main # mainブランチへのプルリクエストに対して実行

jobs:
  textlint:
    name: lint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Initiate npm
        run: npm init -y

      - name: Install textlint
        run: npm install --save-dev textlint # textlintをインストール

      - name: Install packages
        run: npm install textlint-rule-preset-ja-technical-writing # textlintの機能を拡張するためのパッケージをインストール

      - name: Execute textlint
        run: npx textlint --config .textlintrc.json "docs/**" # docs/ディレクトリ配下の全てのファイルをチェック対象にチェックする

textlintの設定

.textlintrc.json

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-exclamation-question-mark": false, //クエスチョンマークとか使えるようにしたいから false
      "ja-no-weak-phrase": false // 「思う」を使えるようにしたいから false
    },
    "no-doubled-conjunction": true
  }
}

実行結果

読みづらい文章が残っている時の出力の様子

Run npx textlint --config .textlintrc.json "docs/**"
  npx textlint --config .textlintrc.json "docs/**"
  shell: /usr/bin/bash -e {0}

/home/runner/work/job_history/job_history/docs/書類1.md
Error:    3:5    error    文末が"。"で終わっていません。                                                                ja-technical-writing/ja-no-mixed-period
  15:18   error    一文に二回以上利用されている助詞 "は" がみつかりました。

次の助詞が連続しているため、文を読みにくくしています。

- "は"
- "は"

同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。
  ja-technical-writing/no-doubled-joshi
  26:93   error    "！" が連続して2回使われています。                                                            ja-technical-writing/ja-no-successive-word
  26:94   error    "！" が連続して2回使われています。                                                            ja-technical-writing/ja-no-successive-word
  26:103  error    一文に二回以上利用されている助詞 "に" がみつかりました。

次の助詞が連続しているため、文を読みにくくしています。

- "に"
- "に"

同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。
  ja-technical-writing/no-doubled-joshi
  60:7    error    漢字が7つ以上連続しています: 特許申請準備中                                                   ja-technical-writing/max-kanji-continuous-len
  73:22   ✓ error  Disallow to use 半角カタカナ: "｡"                                                             ja-technical-writing/no-hankaku-kana

/home/runner/work/job_history/job_history/docs/書類2.md
Error:     3:19  error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period
Error:    39:9   error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period
Error:    72:9   error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period
Error:   112:9   error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period
Error:   152:4   error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period
Error:   181:4   error  文末が"。"で終わっていません。  ja-technical-writing/ja-no-mixed-period

✖ 19 problems (19 errors, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

Error: Process completed with exit code 1.

読みづらさを生み出す要因をしっかりと検知してくれています。

今回は、textlintの拡張パッケージとして、textlint-rule-preset-ja-technical-writingをインストールしており、それをベースに検知してくれていますが、検知対象とする条件を変更することも可能です。

今回の場合は、.textlintrc.jsonでその条件を変更しています。
（自分用のメモのように職務経歴書をgithubで管理したかったため、「！」や「？」を使えるようにしておきたかったことと、「思う」のような表現も自由に使えるようにしておきます。推敲することが目的ではなく、思いをある程度読みやすい文章で、かつ思うがままに書き下せるようにしておきたかったので。）

.textlintrc.json

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-exclamation-question-mark": false, //クエスチョンマークとか使えるようにしたいから false
      "ja-no-weak-phrase": false // 「思う」を使えるようにしたいから false
    },
    "no-doubled-conjunction": true
  }
}

まとめ

• textlintというツールをGithub Actionsで利用し、職務経歴を管理できるようにした。
• textlintのインストールは（個人的には）クセがある。
• 職務経歴の管理、意外にも仕事でのドキュメンテーションでもこういったツールを使うことで、読みやすい文章を担保することができるようになると思う。
• 今後の発展としては、markdownlintというマークダウンの書き方をより良くするためのチェッカーツールもあるようなので、そういったツールを入れるとより便利かもしれない。