注目の記事

プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ

しんや

2020.07.30

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

直近携わっているプロダクトで「ユーザーガイド」的なドキュメントを作る機会があり、暫く前に幾つか見繕ってみた結果「MkDocs」というツールを選定して環境を作成＆整備して来ました。個人的にこのツールは使い勝手がとても良いと思っており、継続して使って来ていました。

当エントリでは今後の備忘録としてMkDocsの基本的な導入・設定方法と、そのMkDocsで適用させたスタイル「Material for MkDocs」をここまで使ってきた中での個人的Tipsなどをまとめておきたいと思います。

目次

　

MkDocsとは

MkDocsは、プロジェクトドキュメントの構築に向けた、高速でシンプルかつリッチな静的サイトジェネレーターです。ドキュメントのソースファイルはMarkdownで記述することが出来、単一のYAML構成ファイルで構成されます。

その他特徴としては以下があります。

  • GitHubページ、Amazon S3、または他の任意の場所でホストできる完全に静的なHTMLサイトを構築可能
  • 見栄え(テーマ)を簡単に切り替え可能
  • ドキュメントを書きながらプレビューが可能(変更を保存するたびに、ブラウザが自動的に再読み込みされて更新される)
  • テーマやプラグインをインストールすることでプロジェクトをカスタマイズ可能

　

MkDocsのインストール

現行最新のMkdocsはPython3系で稼働します。導入対象の環境(MacOSX)は初期設定でPython2系が入っていたのでまずはこの環境を切り替えたいと思います。

MacOSXのバージョンは以下。

% sw_vers
ProductName:	Mac OS X
ProductVersion:	10.15.3
BuildVersion:	19D76

現行Python導入バージョンの確認：

% python --version
Python 2.7.16

pyenvの導入

手っ取り早い切り替え方法としてpyenvを導入し、Python3系の環境を別途用意して行きます。brewを利用可能な状態にセットアップしておき、brewコマンドでpyenvをインストール。各種PATH指定に関しても指定の内容で済ませておきます。pyenv --versionコマンドで所定のバージョンが表示されればOKです。

% brew install pyenv
% echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
% echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
% echo 'eval "$(pyenv init -)"' >> ~/.bash_profile
% source ~/.bash_profile
% pyenv --version     
pyenv 1.2.20

Python3.8系の最新バージョンを導入します。導入可能なバージョンの一覧を確認し、

% pyenv install --list | grep "3.8"
  3.8.0
  3.8-dev
  3.8.1
  3.8.2
  3.8.3
  3.8.4
  3.8.5
  miniconda-3.8.3
  miniconda3-3.8.3

インストール実行。対象バージョンが導入されたことを確認します。

% pyenv install 3.8.5
% pyenv global 3.8.5                              
% pyenv rehash
% pyenv versions
  system
* 3.8.5 (set by /Users/xxxxxxx/.pyenv/version)
% python --version      
Python 3.8.5

Mkdocsのインストール

Mkdocsのインストールはpipを使って行います。

% pip --version 
pip 20.1.1 from /Users/xxxxxxx/.pyenv/versions/3.8.5/lib/python3.8/site-packages/pip (python 3.8)

pip install mkdocsでインストール実施。mkdocs --versionコマンドでバージョン情報が表示されればインストール完了です。

% pip install mkdocs
% mkdocs --version
mkdocs, version 1.1.2 from /Users/xxxxxxx/.pyenv/versions/3.8.5/lib/python3.8/site-packages/mkdocs (Python 3.8)

　

基本操作

プロジェクト新規作成：mkdocs new (プロジェクト名)。

% mkdocs new devio-test
INFO    -  Creating project directory: devio-test 
INFO    -  Writing config file: devio-test/mkdocs.yml 
INFO    -  Writing initial docs: devio-test/docs/index.md

ドキュメントサーバの起動：mkdocs serve。停止はcommand+Cで行けます

 % mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  Documentation built in 0.12 seconds 
[I 200724 08:37:15 server:296] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 200724 08:37:15 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 200724 08:37:15 handlers:64] Start detecting changes
INFO    -  Start detecting changes

サーバ起動後、http://localhost:8000/にアクセスする事によって生成内容を確認出来ます。

デプロイ用コンテンツの作成：mkdocs build。「site」ディレクトリと共に配下に静的コンテンツが諸々作成されます。出来上がったコンテンツを任意のWebサーバ等にデプロイすれば出来上がり。--cleanオプションを付けて実行することで「site」配下の古いファイルを削除した上で作成が行えます。

% mkdocs build --clean
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /Users/xxxxxxx/Desktop/project/devio-test/site 
INFO    -  Documentation built in 0.08 seconds

ページはMarkdownファイル(*.md)として作成し、Markdown形式またはHTML形式での記載内容を認識・表示します。

% vi docs/index.md
# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

## クラスメソッド
こんにちは！こんばんわ！

- [コーポレートサイト](https://classmethod.jp)
- <a target="_blank" href="https://dev.classmethod.jp/">クラスメソッド発「やってみた」系技術メディア | Developers.IO</a>

サーバを起動させたまま編集・保存を行うことも可能なので、保存後にリアルタイムで編集内容が反映されて確認もズムーズに行えます。

　

各種設定・定義について

MkDocsでは、諸々の設定は全てmkdocs.ymlという設定ファイルに書き入れていくことで対応します。プロジェクト作成直後の設定ファイルの中身は以下のような非常にシンプルな内容となっています。ここに、(個人的に必要と思った)設定を追加していきながらその内容について解説していきます。

% vi mkdocs.yml
site_name: My Docs

　

サイト名の変更・ベースドキュメントフォルダの指定

site_nameではドキュメントサイトの名称を指定可能です。また、docs_dirで任意のドキュメントルートフォルダを指定することも可能です。(初期設定はdocs)

site_name: Developers.IO ブログ用MkDocs
docs_dir: 'docs'

Copyrightの指定

copyrightでは著作権情報に関する記載を指定可能です。

# Copyright
copyright: 'Copyright © 2010 - 2020 - Classmethod, Inc.'

　

テーマに関する設定

themeではMkDocsの表示スタイルに関する設定を行えます。直近使ってた設定ファイルは以下のようなものでした。

theme:
    name: material
    language: ja
    icon:
        logo: material/school
        repo: fontawesome/brands/git-alt
    favicon: favicon.png
    # タブ表示を有効.
    features:
        - tabs

個別テーマの導入と適用

MkDocsでは、MkDocs本体とは別に個別テーマの導入を行うことで、表示スタイルの変更を行うことが可能です。

個人的は下記の「Material for MkDocs」が好きで良く使っています。

ライブラリをpipコマンドでインストールし、

% pip install mkdocs-material

theme配下にてnameで対象テーマの指定を行うことで適用されます。

theme:
    name: material

スタイル適用後の画面です。ガラリと雰囲気変わりましたね。

※以降の設定は「Material for MkDoc」テーマで動作確認した内容となります

言語指定

検索インデックスを構築するときに使用する言語を指定。

language: ja

アイコン指定

サイト名と併せて表示されているアイコン画像を個別に指定可能です。

icon:
    logo: material/school
    repo: fontawesome/brands/git-alt

Favicon指定

任意の画像を用意し、faviconでその画像を指定することでfaviconとして表示させることが出来ます。(docsをルートとするパス指定)

favicon: favicon.ico

　

タブ形式のメニュー表示

theme配下に以下の形で設定を追記することで、メニュー構成を「タブ配置を踏まえた」形に変更することが出来ます(後述するnavの1階層目をタブで切り替えできるようにするオプション)。

features:
    tabs: true

上記設定を踏まえて、ページ構成を以下のような形で記載します。navは構成上最上位に来る要素です。インデントを経て次の階層(1階層目)の部分が、メニュー上でタブ表記される形になります。

# Navigation
nav:
    - はじめに: index.md
    - クラスメソッドについて:
        - クラスメソッドとは: classmethod.md
    - CLPについて:
        - CLPとは: clp.md

設定に沿う様にファイルも新しく作成。

% touch docs/classmethod.md
% touch docs/clp.md

以下の様に表示が変わったことが確認出来ました。ページ数自体がそもそも多くなるような場合であれば、この構成を取ることでよりスッキリした形で情報を整えられるかと思います。

　

ページの作成・構成・相対パス

基本的なファイル構造に関する内容の詳細は以下。任意のフォルダ構造を持った形を取ることが出来、ページの指定もそこからフォルダを踏まえた記載の形式を取ることでリンクされるようになります。

mkdocs.yml

nav:
    - はじめに: index.md
    - クラスメソッドについて:
        - クラスメソッドとは: classmethod.md
        - メニュー:
            - サービス: menu/services.md
            - 事例: menu/usecases.md
            - セミナー・相談会: menu/seminar.md

上記ファイル構造を踏まえた形でフォルダ及びファイルを配置。

% pwd
/Users/xxxxxx/xxxxxx/xxxxxx/devio-test
% mkdir docs/menu/
% touch docs/menu/services.md
% touch docs/menu/usecases.md
% touch docs/menu/seminar.md

Markdownファイルの内容を以下のような形式で書くことで、

classmethod.md

# クラスメソッド

- [サービス](menu/services.md)
- [事例](menu/usecases.md)
- [セミナー・相談会](menu/seminar.md)

以下のような形でコンテンツを表示・リンクさせることが可能です。

　

本文内容の記述

MkDocsはmdファイル内にMarkdown形式、及びHTML形式で内容を記述することが可能です。混在も可能。

　

画像の表示

前述のフォルダ、ファイル構成と同様に、当該ページから参照可能なパス形式で画像ファイルを指定することで表示が可能です。(※下記ページ「Linking to images and media」から抜粋)

Cupcake indexer is a snazzy new project for indexing small cakes.

![Screenshot](img/screenshot.png)

*Above: Cupcake indexer in progress*

　

カスタムCSSの設定

extra_cssで別途ファイルを指定することで任意のCSSスタイル定義を適用させることが可能です。

extra_css:
    - css/custom.css

必要な構成を準備し、

% mkdir docs/css        
% touch docs/css/custom.css

CSS設定ファイルに内容を追記。

custom.css

/** ヘッダーカラーを緑色に. */
.md-header {
    background-color: #006633;
    color: #fff;
}

.md-tabs__inner {
    background-color: #006633;
}

nav.md-tabs {
    background-color: #006633;
}

.md-tabs--active {
    color:#ffffff !important;
}

個別のCSS設定を効かせることが出来ました。

　

日本語検索対応

MkDocsではドキュメント内の検索も行えます。公式ドキュメントでは幾つか検索有効化のための設定が紹介されていたのですが、

直近試した感じだと、ここまでの設定に新たに何かを加える事無く、検索出来ているようでした(language: ja で表示言語を日本語にしたくらい)。 もうちょっと複雑な設定だと追加で何か必要になるのかな？この辺は別途稿を改めて深堀り出来ればと思います。

その他Markdown拡張

その他、個人的に良さそうだなと思って追加した設定は主に以下の内容。

markdown_extensions:
    - admonition
    - codehilite:
        linenums: true
        guess_lang: false
        use_pygments: false
        noclasses: true
    - toc:
        permalink: true
    - fontawesome_markdown
admonition:
注意書きや警告など、ユーザーの目を引く様なテキスト表示を行う時に使える装飾。
Admonitions - Material for MkDocs
codehilite
コードブロックに関する表記設定。
Code blocks - Material for MkDocs
toc
見出しに関する設定。ここでは見出し末尾にアンカーリンクを表示させています。
Setting up navigation - Material for MkDocs
fontawesome_markdown
Webアイコンフォントの表示。

　

mkdocs.yml設定サンプル

このエントリで紹介した「MkDocsで出来ること」はほんの一部であり、他にも色々な機能や設定・カスタマイズが可能です。関連ドキュメントを参考に色々深堀りしてみて頂ければと思います。

mkdocs.yml

site_name: Developers.IO ブログ用MkDocs
docs_dir: 'docs'


theme:
  name: material  # MkDocs for Materialに表示スタイルを切替.
  language: ja    # メニュー言語を日本語に変更.
  icon:           # サイト名横のアイコン画像を変更.
    logo: material/school
    repo: fontawesome/brands/git-alt
  favicon: images/favicon.png  # ファビコン画像の設定.
  features:
    - tabs   # タブ表示を有効化.


# Navigation
nav:
    - はじめに: index.md
    - クラスメソッドについて:
        - クラスメソッドとは: classmethod.md
        - メニュー:
            - サービス: menu/services.md
            - 事例: menu/usecases.md
            - セミナー・相談会: menu/seminar.md
    - CLPについて:
        - CLPとは: clp.md


markdown_extensions:
    - admonition
    - codehilite:
        linenums: true
        guess_lang: false
        use_pygments: false
        noclasses: true
    - toc:
        permalink: true
    - fontawesome_markdown


extra_css:
    # ユーザー個別で効かせたい設定を記述.
    - css/custom.css
    # fontawesome_markdownで使える設定を別途追加.
    - "https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css"


# Copyright
copyright: 'Copyright © 2010 - 2020 - Classmethod, Inc.'

　

気になったことなど

　

国際化対応は？

関連してそうなトピックを参照する限り、MkDocsでは国際化(i18n)対応に関する公式的な仕組みは現状提供されていない模様。惜しい。

　

まとめ

という訳で、静的サイトジェネレータツール、「MkDocs」の紹介でした。

比較的簡単且つスムーズに「良い感じのドキュメント体制」を準備出来るのはMkDocsの良いところだなーと個人的には思っています。ただ1点「多言語対応」が為されていないのが気になるところではありました。この辺りが必要になってくるケースになるのであれば、MkDocs以外のツールを選ばざるを得ないところなのかな...と思っております。MkDocsは引き続き活用しつつ、「多言語対応」の機能も踏まえたツールやサービスを幾つか試してみたいと思います。

customer-story-analytics

関連記事

Material for MkdocsにCustomizationを使ってサイト分析ツールを導入してみた

たかやま

2023.10.30

Material for MkDocsのタイトルテキストをリンクテキストにする

たかやま

2023.10.24

ドキュメントの文法(シンタックス)【CCG執筆者向け】

川原征大

2023.09.11

「Classmethod Cloud Guidebookの裏側」というビデオセッションで話しました #devio2023

たかやま

2023.08.02