自分が過去にHonkitで書いていたドキュメントに対してmarkdownlintを導入しました。
導入手順は以下の通りです。今回はmarkdownlint-cli2を使いました。
npm install --save-dev markdownlint-cli2
次に`npm run lint`でlintを実行できるように仕組みます。
まずは.markdownlint-cli2.jsoncを作成します。
{ "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json", "default": true, "config": { "MD013": { "line_length": 800 } } // 行の長さを800文字に制限 }
jsoncはjsonに対してコメントがつけられるという仕組みです。ここではMD013ルールの行の長さを800としています。これは日本語で書いているドキュメントなので一行が80文字は短いという観点から抑制をするためです。
続いて、markdownlint-cli2を実行するようにpackage.jsonのscriptsの項目に記載をします。
{ "name": "vector_tile_book", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "build": "honkit build", "serve": "honkit serve", "lint": "markdownlint-cli2 --config .markdownlint-cli2.jsonc '**/*.md' '#node_modules' '#_book'", "prebuild": "npm run lint" }, "keywords": [], "author": "Taro Matsuzawa <btm@tech.email.ne.jp> (https://smellman.hatenablog.com/)", "license": "ISC", "devDependencies": { "honkit": "^6.0.2", "markdownlint-cli2": "^0.17.1", "send": "^1.1.0" } }
markdownlint-cli2ではまず'**/*.md'と指定することで全てのmarkdownを処理するようにしています。
また、'#node_modules'、'#_book'と#から指定することで、除外するファイルを設定します。
あとはnpm run lintをして、エラーを確認してひたすら直していきます。僕の作ったレポジトリでは100件近くエラーがでていたので手動で直しましたが、プロジェクトによっては`--fix`をつけて自動的に修正するという仕組みを使うとよいでしょう。
次にGitHub Actionsで必ずmarkdownlintが通るように設定をします。
name: Publish # Publish npm and dockerhub when Release Pull Request is merged # # https://hub.docker.com/r/honkit/honkit on: push: branches: - main jobs: lint: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: DavidAnson/markdownlint-cli2-action@v19 with: globs: '**/*.md' build: needs: lint runs-on: ubuntu-24.04 permissions: contents: write concurrency: group: ${{ github.workflow }}-${{ github.ref }} steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v2 with: node-version: 22 - name: Restore npm cache id: restore-cache uses: actions/cache@v4 with: path: node_modules key: js-depend-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} - name: npm install if: steps.restore-cache.outputs.cache-hit != 'true' run: npm install - name: build docs run: npx honkit build - run: touch _book/.nojekyll - name: Deploy id: deployment uses: actions/upload-pages-artifact@v3 with: path: _book deploy: runs-on: ubuntu-24.04 needs: build permissions: pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4
上記のyamlファイルではlint jobとbuild jobが依存関係にあります。lintが成功しない限りbuildは動かないため、markdownがlintを通ってない場合はGitHub Pagesにアップロードされることはありません(build jobとdeploy jobが依存関係にあります)。
今回作ったレポジトリは以下の物です。
まだPull Requestに対してmarkdownlintを書けるようにしてないというか、書いてるのが僕だけなので直接mainにぶち込んでるという状況なので、これから改善していきたいと思います。
あと、そもそもこのレポジトリの内容自体古いので内容の更新や追記などをしていきたいと思います。
ではでは。