Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた
こんにちは。たかやまです。
Material for MkdocsではSite Analytics(サイト分析ツール)を導入することができます。
Google AnalyticsはMaterial for Mkdocsのテーマでネイティブにサポートされており簡単に導入することができます。
extra:
analytics:
provider: google
property: G-XXXXXXXXXX
Setting up site analytics - Material for MkDocs
一方で、Google Analytics以外のサイト分析ツールを導入する場合は、Material for MkdocsのCustomizationを利用して導入する必要があります。
今回は、Material for MkdocsのCustomizationを利用してJavaScriptのトラッキングコードを提供するようなマーケティングオートメーションツールを導入する方法を紹介します。
さきにまとめ
CustomizationのOverriding blocksを利用し、libsまたはscriptsブロックを利用してトラッキングコードを導入する
Overriding blocks - Material for MkDocs
やってみる
検証環境
以下の手順に沿って環境を用意します。
# (必要に応じて)仮想環境作成 python3 -m venv .venv && source .venv/bin/activat # Material for Mkdocs環境作成 pip3 install mkdocs-material mkdocs new . echo -e "\ntheme:\n name: material" >> mkdocs.yml mkdocs serve
mkdocs serveを実行するとlocalhost:8000でサイトが表示されます。
ブロックカスタマイズ
検証環境作成段階でのディレクトリ構成は以下のようになっています。
. ├─ docs/ │ └─ index.md └─ mkdocs.yml
ここからブロックカスタマイズの設定を行っていきます。
サポートされているブロックは以下の通りです。
| ブロック名 | 目的 |
|---|---|
| analytics | Google Analytics統合をラップします |
| announce | アナウンスバーをラップします |
| config | JavaScript アプリケーション構成をラップします |
| container | メインコンテンツコンテナをラップします |
| content | メインコンテンツをラップします |
| extrahead | カスタムメタタグを追加するための空のブロック |
| fonts | フォント定義をラップします |
| footer | フッターをナビゲーションと著作権で囲みます |
| header | 固定ヘッダーバーをラップします |
| hero | ヒーロー ティーザーをラップします (利用可能な場合) |
| htmltitle | <title>タグをラップします |
| libs | JavaScript ライブラリ (ヘッダー) をラップします |
| outdated | バージョン警告をラップします |
| scripts | JavaScript アプリケーションをラップします (フッター) |
| site_meta | ドキュメントのヘッダーでメタタグをラップします |
| site_nav | サイトのナビゲーションと目次をラップします |
| styles | スタイルシートをラップします(追加のソースも) |
| tabs | タブナビゲーションをラップします(利用可能な場合) |
Customization - Material for MkDocs
トラッキングコードは多くは<head>内か</body>付近に設定することになると思います。
JavaScriptのトラッキングコードを<head>内に導入する場合にはlibsブロック、</body>付近に導入する場合にはscriptsブロックを利用して設定していきます。
では、実際に設定するための定義ファイルを作成していきます。
ブロックカスタマイズを定義するためのファイルはoverrridesディレクトリを作成し、main.htmlとして配置します。
. ├─ docs/ │ └─ index.md ├── overrides/ │ └──main.html └─ mkdocs.yml
main.htmlにはカスタマイズしたいブロックを{% block xxx %}}形式で指定します。
完全にコンテンツを上書きするのではなく、元のコンテンツを継承する場合には{{ super() }}を記載するのを忘れないようにしてください。
また、{{ super() }}前後によるコードの挿入位置によって、実際のコードの挿入位置も変わってくるのでユースケースに合わせて設定してください。
{% extends "base.html" %}
{% block libs %}
<!-- 元のコンテンツより前に実行したいコード -->
{{ super() }}
<!-- 元のコンテンツより後に実行したいコード -->
{% endblock %}
{% extends "base.html" %}
{% block scripts %}
<!-- 元のコンテンツより前に実行したいコード -->
{{ super() }}
<!-- 元のコンテンツより後に実行したいコード -->
{% endblock %}
サンプルとしてconsole.log("Hello World!");を出力するようなJavaScriptのコードを定義したファイルは以下のようになります。
※ここではlibsブロックとscriptsブロックの両方にコードを設定しています。
{% extends "base.html" %}
{% block libs %}
<script>
console.log("Hello World!");
</script>
{{ super() }}
{% endblock %}
{% block scripts %}
{{ super() }}
<script>
console.log("Hello World!");
</script>
{% endblock %}
main.htmlを作成したら、カスタマイズ機能を有効にするためにmkdocs.ymlに以下の設定を追加します。
site_name: My Docs theme: name: material custom_dir: overrides
動作確認
カスタマイズができたら、mkdocs serveを実行して動作確認を行います。
<head>と<body>内にJavaScriptのトラッキングコードが設定されていることを確認します。
ブラウザの開発者モード等で想定箇所にコードが設定されていればOKです！
後はお使いのマーケティングオートメーションツールでちゃんと情報が取得されているか確認いただければと思います。
最後に
今回はMaterial for MkdocsのCustomizationを使ってサイト分析ツールを導入する方法を紹介しました。
テーマでネイティブにサポートされていない機能についても、カスタマイズ機能を利用することで実現することができます。
こちらの記事が同様の悩みを持っている方への助けになれば幸いです。
以上、たかやま(@nyan_kotaroo)でした。
