きちんとしたガイドを書く、そしてそのガイドを多人数で変更するというケースでは、文章の揺れ等をできるだけ防ぎたい。このため、GitLab CI/CD で textlint を導入したい。

textlint 用 Docker Image の作成

Docker Hub を探してみたのですが、広く使われている textlint のイメージは無いようでした。それぞれのドキュメントで必要なルールも異なるということも多分に影響しているのでしょう。このため、自分で Docker Image をビルドし、Container Registry へと push することにしました。

Dockerfile はこんな感じにしました。package.json と package-lock.json を組み込んで npm install するだけです。

FROM node:current-alpine3.11

COPY ./package*.json ./
RUN npm install

ENTRYPOINT ["textlint"]

ルールやフィルタは以下を有効にしています。詳細な設定については .textlintrc に記載します。

フィルタ

textlint-filter-rule-comments
-  と  で囲まれた箇所を textlint の対象外にできるフィルタです
textlint-filter-rule-whitelist
- 特定のパターンに合致する文字列を textlint の対象外にできるフィルタです。

それぞれについては、以下の Qiita 記事が参考になります。

ルール

preset-ja-technical-writing
- 技術文書向けのルールプリセットです
- 本 Blog のエントリもこのルールでチェックしていて、よく 1文の長さは100文字以下とするや読点は1文中に3つまでというルールに怒られます
textlint-rule-spellcheck-tech-word
- 技術用語に対するルールです
textlint-rule-preset-ja-spacing
- 日本語文書のスペーシングに対するルールです。日本語で論文を書くとき、よく英単語と日本語との間にスペースを入れるように指導されますが、そのあたりを制御できます。
  - HTML 化する場合は、スペースをあけると微妙なスペース空いたりするので
textlint-rule-prh
- 単語の揺れを防ぐためのルールです
- WEB+DB Press 用の設定を見れば、どういうことができるかワクワクするのではないでしょうか

Docker Image の build、push

GitLab は無料で Container Registry の機能を使用できます。このため、Dockerfile や package.json などに変更があった場合に build-textlint ジョブを起動させるようにしました。当該ジョブで Image の build と push をするように構成しています。

stages:
  - preflight
build-textlint:
  stage: preflight
  image: docker:${DOCKER_VERSION}
  services:
    - docker:${DOCKER_VERSION}-dind
  only:
    changes:
      - "docker/textlint/*"
  before_script:
    - docker login -u ${CI_REGISTRY_USER} -p ${CI_JOB_TOKEN} ${CI_REGISTRY}
  script:
    - docker build -t ${CI_REGISTRY}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}/textlint:latest docker/textlint
    - docker push ${CI_REGISTRY}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}/textlint:latest

DinD を使っていますが、技術的な詳細をしっかり理解できていません。このあたりは勉強しないといけないなぁと思っています。

textlint の適用

textlint を実行するジョブは非常にシンプルですね。 markdown ドキュメント等に変更があった場合に、全ドキュメントに対して textlint を実行するだけです。

textlint:
  stage: lint
  image:
    name: ${CI_REGISTRY}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}/textlint
    entrypoint: [""]
  script:
    - npx textlint "**/*.md"
  only:
    changes:
      - "**/*.md"
      - .gitlab-ci.yml
      - .textlintrc
      - prh.yml
      - docker/textlint/Dockerfile