CI で使う

自動化する価値があるのは 2 つです。Pull Request ごとにドキュメントを検証することと、既定ブランチやタグの更新時に配布用の HTML / PDF を生成することです。monodocs は普通の npm CLI なので、専用の Action やプラグインは要りません。npm / npx でインストールし、ローカルと同じコマンドを実行します。

CI に必要なもの

要件	対象
Node.js 22.12.0 以上	すべて
Chromium または Google Chrome	--format pdf / --format both と mermaid.mode: pre-render のみ
ビルド時のネットワーク	mermaid.mode: client で CDN ランタイムを使う場合のみ

validate はエラーを検出すると終了コード 1 を返すので、Pull Request のゲートに使えます。HTML 出力と validate はブラウザを起動しません。

ビルドを再現可能にするため、バージョンは固定してください。devDependency として追加して（npm install -D monodocs）npm exec から呼ぶか、npx に厳密なバージョンを渡します。

IMPORTANT

固定した値は更新し続けてください。セキュリティ修正は新しいバージョンとしてのみ公開されます。サポート対象は npm の latest が指す版だけで、バックポートはしません（セキュリティポリシー）。固定値の更新は Dependabot や Renovate に提案させ、リポジトリのセキュリティアドバイザリを購読してください。monodocs は依存物を公開 CLI にバンドルしているため、lockfile を読むスキャナに見えるのは monodocs だけで、その中のライブラリは見えません。

GitHub Actions

Pull Request で検証する

name: Docs

on:
  pull_request:
    paths: ['docs/**', 'monodocs.config.yml']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx --yes monodocs@0.19.0 validate ./docs

単一 HTML と PDF を生成する

GitHub ホストランナーには Google Chrome が同梱されており、monodocs が自動検出するので、ubuntu-latest と windows-latest では PDF 生成に追加設定は不要です。

name: Build docs

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      # 日本語・絵文字を含む PDF を出力する場合だけ必要。HTML のために pre-render する図のラベルに数式があるなら fonts-lmodern も入れる。
      - name: Install fonts
        run: sudo apt-get update && sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji

      - name: Build HTML and PDF
        run: npx --yes monodocs@0.19.0 build ./docs --format both -o ./dist

      - uses: actions/upload-artifact@v4
        with:
          name: manual
          path: dist/

--format both では -o をディレクトリとして扱い、docs.html と docs.pdf を出力します（0.8.0 以前は manual.html と manual.pdf）。

リリースに添付する場合は、ワークフローを release: types: [published] で起動し、ジョブに permissions: contents: write を与えて、upload ステップを次に置き換えます。拡張子でファイルを選ぶので、どのバージョンを固定していても動きます。

      - name: Attach to the release
        run: gh release upload "$GITHUB_REF_NAME" dist/*.html dist/*.pdf
        env:
          GH_TOKEN: ${{ github.token }}

GitHub Pages で公開する

単一 HTML は自己完結しているため、公開は Pages の成果物に 1 ファイルをコピーするだけです。このリポジトリの deploy-site.yml も、VitePress サイトと併せてそうしています。

GitLab CI

docs:
  image: node:22-bookworm-slim
  script:
    - npx --yes monodocs@0.19.0 validate ./docs
    - npx --yes monodocs@0.19.0 build ./docs -o ./dist/docs.html
  artifacts:
    paths: [dist/]

node イメージにはブラウザが入っていません。PDF も生成するジョブでは、Chromium とフォントを追加します。

  before_script:
    - apt-get update
    - apt-get install -y chromium fonts-noto-cjk fonts-noto-color-emoji
  variables:
    PUPPETEER_EXECUTABLE_PATH: /usr/bin/chromium

注意点

• Chromium の検出：PUPPETEER_EXECUTABLE_PATH が常に最優先です。未指定の場合、Linux と Windows では標準のインストール先を探索します（Windows では Chromium ベースの Microsoft Edge にフォールバックします）。コンテナイメージと macOS では明示的に指定してください。
• フォントはランナー側のもの（PDF の数式を除く）：フォントが無い文字は PDF で tofu（□）になります。日本語には fonts-noto-cjk、絵文字には fonts-noto-color-emoji が必要です。PDF の数式は monodocs が持っている数式用のフォントで組むので、ランナーに数式用のフォントは要りません。テーマが math に自分のフォントを指定するときは、テーマがそれを埋め込むか、ランナーに入れておきます（math を参照）。mermaid.mode: pre-render で HTML を書き出すときは、ビルドが HTML の SVG にある図のラベルを、数式も含めてランナーのフォントで組みます。そのため、ラベルの数式にはランナーに数式用のフォント（fonts-lmodern の Latin Modern Math など）が要ります。それ以外の HTML は閲覧側のフォントを使うため影響を受けません。ランナーが描けない文字があるときや、テーマが指定した数式のフォントに OpenType MATH テーブルが無いとき（font/no-math-table）は、ビルドが警告します。fontCheck: error にすれば、その警告でジョブを落とせます。
• オフラインビルド：mermaid.mode: client は既定で CDN からランタイムを読み込みます。ランナーが外部ネットワークに出られない場合は inline か pre-render を使ってください。
• 警告では build も validate も失敗しない：リンク切れやタイトルの欠落は報告され、出力も生成されます。警告でも validate を失敗させるには --strict を付けてください。

関連ページ

• コマンドオプション：上記で使ったフラグと終了コード。
• 設定ファイル：ここで触れた mermaid、pdf、assets の各キー。