コードの品質番人「pre-commit」公式サイトの中身を読み解く：Mako テンプレートで動く静的サイトの全貌

ひとことでいうと

このリポジトリは、Git の pre-commit フレームワークの公式ドキュメントサイト pre-commit.com を作るためのソースコード一式です。「pre-commit というツール自体」ではなく、「そのツールを紹介するウェブサイトを生成する仕組み」が収録されています。Python の Mako テンプレートエンジンと SCSS（スタイルを書くための言語）を組み合わせて HTML を自動生成し、GitHub Actions（クラウド上の自動実行サービス）でデプロイ（公開）まで行います。サイトの仕組みを学べるだけでなく、pre-commit フレームワーク本体の使い方を理解するリファレンスとしても役立ちます。

こんな人におすすめ

チーム開発でコードの品質を自動でそろえたい人: Python・JavaScript などを複数人で書いていると、書き方のブレや細かいミスが積み重なります。pre-commit を使えば、コミット（変更の保存）のたびに自動でチェックが走り、全員のコードを一定の品質に保てます。本サイトにはその導入手順が詳しくまとめられています。
Python で静的サイトを自作・カスタマイズしてみたい人: Mako テンプレート＋ Python スクリプトというシンプルな構成で、ウェブサイトをどう生成するかが一目でわかります。Jinja2 や Sphinx（どちらも Python 製のサイト生成ツール）とは異なる軽量なアプローチを学べる、実践的な手本です。
GitHub Pages でドキュメントサイトを公開したいオープンソース開発者: このリポジトリは、ビルド（生成）からデプロイ（公開）まで GitHub Actions で完全自動化されています。CI/CD（継続的なビルド・デプロイの仕組み）付き静的サイト運用のテンプレートとして、そのままトレースして使えます。

インストール・使い方

ローカル（自分のパソコン）でサイトをビルドするには、Python と Node.js（SCSS のコンパイルに使用）が必要です。以下の手順は「ターミナル」、つまり文字を打ち込んでパソコンに命令を送る画面で実行します。コマンドはコピー＆ペーストで貼り付けてかまいません。

Step 1: リポジトリを手元にコピーして、必要なライブラリを入れる

git clone https://github.com/pre-commit/pre-commit.com.git
cd pre-commit.com
pip install -r requirements-dev.txt
npm install

git clone でリポジトリ（ソースコードの置き場）を丸ごとダウンロードします。pip install と npm install で、Python・Node.js それぞれの依存ライブラリを一括インストールします。requirements-dev.txt に Mako などが、package.json に SCSS コンパイラ関連が定義されています。

Step 2: テンプレートを HTML に変換してサイトをビルドする

make build
# または直接
python make_templates.py

make_templates.py が .mako 形式のテンプレートファイルと sections/ ディレクトリ内の Markdown ファイルを読み込み、静的 HTML を出力します。共通のユーティリティ関数は template_lib.py にまとめられており、テンプレート側から呼び出す仕組みです。

Step 3: ブラウザでローカルプレビューを確認する

python -m http.server 8000

このコマンドを実行したあと、ブラウザ（Chrome や Safari など）のアドレスバーに http://localhost:8000 と入力すると、生成したサイトが表示されます。Ctrl + C でサーバーを停止できます。

（参考）pre-commit フレームワーク本体を自分のプロジェクトに導入する場合

pip install pre-commit
pre-commit install

自分のプロジェクトのフォルダに .pre-commit-config.yaml（設定ファイル）を作成してから pre-commit install を実行すると、以降は git commit のたびに自動チェックが走るようになります。

動かしてみた

Python 3.12.13 の環境でリポジトリをクローンし、ディレクトリ構成を確認しました。主要なファイルは次のとおりです。

./make_templates.py     ← ビルドの入口となるスクリプト
./template_lib.py       ← 共通ユーティリティ関数
./base.mako             ← サイト全体の骨格テンプレート
./index.mako            ← トップページ用テンプレート
./hooks.mako            ← フック一覧ページ用テンプレート
./sections/usage.md     ← 使い方セクション
./sections/install.md   ← インストールセクション
./sections/cli.md       ← CLI リファレンス
./sections/hooks.md     ← フック解説
./sections/advanced.md  ← 上級者向け設定
./sections/plugins.md   ← プラグイン情報

サイトの骨格は base.mako が担い、各セクション（sections/*.md）のコンテンツがそこに流し込まれる構造になっています。hooks.mako は pre-commit が公式にサポートするフック（自動実行するチェックスクリプト）の一覧ページを生成します。また、biome.json の存在から、JavaScript・TypeScript の静的解析には Rust 製の高速ツール「Biome」を採用していることが確認できます。リポジトリ自体も .pre-commit-config.yaml を持ち、自分自身のコード品質管理に pre-commit を使っているのが読み取れます。

ブラウザで試す

pre-commit.com のサイト上では、よく使われる pre-commit フックをブラウザ上で選択すると .pre-commit-config.yaml の内容を自動で生成してくれるデモが提供されています。使いたいフックにチェックを入れるだけで、そのままコピーして使える設定ファイルが出来上がります。どんなフックが存在するかを把握しながら設定を作れるため、初めて pre-commit を導入するときの第一歩として非常に便利です。

実践のコツ：はじめの一歩でつまずかないために

pre-commit を実際のプロジェクトに導入するときに役立つ、すぐ試せるポイントをまとめます。

まず最小構成から始める: 最初から多くのフックを入れず、trailing-whitespace（行末の余分なスペースを除去）と end-of-file-fixer（ファイル末尾を統一）だけでも十分効果があります。慣れてきたら少しずつ追加するのがおすすめです。
rev はタグ名で固定する: rev: main のようにブランチ名を指定すると、フックの内容が予告なく変わるリスクがあります。v4.6.0 のようなバージョンタグを明記しておくと安全です。
pre-commit run --all-files で既存コードを一斉チェック: 新しいフックを追加したとき、過去のファイルにまとめてチェックをかけられます。大量の修正が出る場合はコミットを分けて整理すると履歴が読みやすくなります。
stages で実行タイミングを分ける: 時間のかかるテストは push 時だけ走らせ、素早いフォーマット修正は commit 時に実行するといった分け方ができます。開発スピードを落とさずに品質を保てます。
ローカルフック（local リポジトリ）で独自チェックを作る: 外部リポジトリに公開していない自作スクリプトも、repo: local と指定することでフックとして登録できます。チーム固有のルールを強制したいときに便利です。
CI/CD でも pre-commit run --all-files を走らせる: ローカルでのチェックを誰かがスキップしても、GitHub Actions 上で同じチェックが通らないとマージできない設定にしておくと、品質管理の網をより確実にできます。

活用アイデア

Python プロジェクトへの Black・Flake8 導入: コードフォーマッター（書き方を統一するツール）の Black とリンター（問題を検出するツール）の Flake8 をフックとして設定すると、書き方のブレをコミット時に自動で揃えられます。チームで「フォーマットで議論する時間」をゼロにできます。
モノレポでの言語別フック管理: files や types パラメーターで適用範囲を絞れるため、Python ファイルには Black、TypeScript ファイルには ESLint のみを走らせる設定が可能です。大規模プロジェクトでも無駄なチェックを省き、実行速度を保てます。
CI/CD パイプラインとの連携: GitHub Actions で pre-commit run --all-files を実行し、ローカルとリモート両方でチェックを通過しないとマージできない仕組みを作れます。コードレビューの負担を大幅に減らせます。
コミットメッセージのルール強制: commit-msg ステージを使うと、コミットメッセージに Jira（課題管理ツール）のチケット番号が含まれているかどうかを自動で検証するフックを作れます。プロジェクト管理の記録を一貫して保てます。
セキュリティスキャンの自動化: detect-secrets や bandit といったフックを追加すると、パスワードや API キーの誤コミットを事前にブロックできます。チームのセキュリティ意識に依存せずに、仕組みとして守れます。
Mako テンプレートを参考にした独自ドキュメントサイトの構築: このリポジトリのビルド構成をベースに、自分のオープンソースプロジェクトや社内ツールのドキュメントサイトを GitHub Pages へ公開する出発点として使えます。Jekyll や Hugo などのフレームワークに頼らず、Python だけでサイトを組み立てる軽量な事例として参考になります。

用語とポイント解説

フック（hook） Git のコミットやプッシュといったイベントに紐付けて自動実行されるスクリプトのことです。かんたんに言うと「ある操作のタイミングで、勝手に動く仕掛け」です。pre-commit はコミット直前に走るフックで、問題があればコミット自体を止めます。

pre-commit コミット前フックをまとめて管理するための Python 製フレームワークです。かんたんに言うと「チェック係を一括で雇う管理ツール」です。.pre-commit-config.yaml に使いたいフックを書くだけで、インストールから実行まで自動で面倒を見てくれます。

Mako Python で書かれたテンプレートエンジン（ひな形から HTML などを生成するツール）です。かんたんに言うと「穴あきの文書に、プログラムから値を流し込んで完成させる仕組み」です。${variable} や <%def> といった独自の記法で、再利用しやすい部品を作れます。

SCSS CSS（ウェブページの見た目を定義する言語）を拡張した記法です。かんたんに言うと「CSS をより書きやすく、まとめやすくしたもの」で、変数やネスト（入れ子）などが使えます。コンパイル（変換）することで通常の CSS に変換され、ブラウザで読み込まれます。

Biome Rust 製の高速な JavaScript・TypeScript 向けリンター（問題検出ツール）兼フォーマッターです。かんたんに言うと「ESLint と Prettier を一本化した、速くて軽いオールインワンツール」です。設定ファイルは biome.json で、このリポジトリでも採用されています。

rev .pre-commit-config.yaml 内でフックのバージョンを指定するフィールドです。かんたんに言うと「どのバージョンのフックを使うかを固定するラベル」です。Git のタグ（v4.6.0 など）またはコミットハッシュを記入することで、予期しないバージョンアップによる動作変化を防げます。

stages フックをどの Git イベントで実行するかを絞り込む設定項目です。かんたんに言うと「フックを起動するタイミングを選ぶスイッチ」です。commit・push・manual などを指定でき、重い処理はプッシュ時だけ走らせるといった使い分けができます。

静的サイト（Static Site） サーバー上でリアルタイムに HTML を生成せず、あらかじめ作成済みの HTML ファイルをそのまま配信するウェブサイトです。かんたんに言うと「毎回料理するのではなく、作り置きをそのまま出すスタイルのサイト」です。表示が速く、サーバー費用を抑えやすいのが利点です。

GitHub Actions GitHub（ソースコードのホスティングサービス）が提供するクラウド上の自動実行環境です。かんたんに言うと「コードをプッシュしたら、決めておいた作業を自動でこなしてくれるロボット」です。本リポジトリでは deploy.yml というワークフローがサイトのビルドとデプロイを担当しています。

テンプレートエンジン（Template Engine） ひな形となるファイルにプログラムからデータを埋め込んで、最終的な出力（HTML など）を生成するツールの総称です。かんたんに言うと「決まった枠組みに内容を差し込んで、完成品を大量生成するコピー機のようなもの」です。Mako・Jinja2・Handlebars などが代表例です。

CI/CD（Continuous Integration / Continuous Delivery） コードの変更を検知するたびに自動でビルド・テスト・デプロイを行う開発スタイルおよびそのパイプラインです。かんたんに言うと「コードを送ったら、検査から公開まで自動でやってくれる流れ作業ライン」です。人手によるミスを減らし、リリースの頻度と安全性を高められます。

コードの品質を継続的に保ちたいチーム開発や、Python でシンプルなドキュメントサイトを構築するプロジェクト、さらには GitHub Actions を活用した CI/CD 自動化の学習など、幅広い場面で役立つ情報が詰まっています。ぜひ自分のチームの pre-commit 導入や、オープンソースプロジェクトのドキュメントサイト自作などに活用してみてはいかがでしょうか。