MkDocsを使って、Markdownがメインのポートフォリオ/ノウハウサイトを作成してみました。

Table of Contents

作成したもの

作成したサイトとGitHubのリポジトリは以下です。

サイト

リポジトリ

経緯

アウトプットの先

学びをアウトプットすることは大事です。
私の場合はアウトプットとして、このブログに投稿していました。

しかし、ブログを書くまでも必要ないアウトプットもあります。

• 参考リンクを貼るだけで解決する場合 (公式の最新を見た方が信頼できる)
• インターネット上で既に似たような情報が多数見受けられる場合

このようなケースをどう扱うか悩んでいました。

GitHubのリポジトリにノウハウを

GitHubはインターネットからアクセスでき、全文検索も可能です。
ブログを書く必要のないものはGitHubのリポジトリにまとめていました。

しかし、しばらく使っていると以下の要望が出てきました。

• GitHub Markdown以上のリッチな機能を使いたい
• 自身の経歴などを記載したポートフォリオサイトにもしたい

そうなるとサイトジェネレータが必要になってきます。

サイトジェネレータの要件

必要な要件は以下の7点でした。

1. 全文検索ができる
2. マクロ構文が使える
3. 追尾型の見出しに対応している
4. デザインが格好いい
5. 基本的にMarkdownで完結する
6. バージョン管理できる
7. レスポンシブ対応(スマホ対応)

本ブログで利用しているHugoも検討しましたが、条件1,3でハマッたため断念しました。

MkDocsを使えば..

そんなとき、Jumeauxで利用しているMkDocsを思い出しました。

JumeauxはPython製であるため、同じPython製のサイトジェネレータとして、ツールのドキュメント作成に選定したものです。
このMkDocsが先ほど挙げた7つの要件を全て満たしていました。

しかも、最近Version1.0になっていたのです😮

MkDocsとは

プロジェクト文書の構築を目的としてサイトジェネレータです。
ドキュメントソースはMarkdownを..設定は単一のYAMLファイルを使います。

MkDocsではテーマやプラグインが利用できます。

Material for MkDocs

見た目が好みで機能も抱負だったため、Material for MkDocsというテーマを使用しています。

Material for MkDocsは抱負なExtentionにも対応しています。
以下のExtentionを利用しています。

要件について

先ほど挙げた要件は以下のように満たせます。

1. 全文検索ができる

Material for MkDocsは検索も提供しています。
他にpluginを使っていなければ特別な設定はいりません。

もし日本語を使う場合はmkdocs.ymlのextra.search.languageに設定が必要です。

extra:
  search:
    language: 'en, ja'

2. マクロ構文が使える

プラグインを使うと、Pythonを利用したマクロが定義できます。

この話をすると長くなるため、別の機会に紹介させてください。

3. 追尾型の見出しに対応している

デフォルトで使用できます。

4. デザインが格好いい

Material for MkDocs カッコイイ( ´▽｀)

5. 基本的にMarkdownで完結する

一部、特殊表記もありますが基本はMarkdownです。

新しくファイルやディレクトリを追加しても、設定(mkdocs.yml)を変更する必要はありません😄

6. バージョン管理できる

GitHubで管理しています。

7. レスポンシブ対応(スマホ対応)

Material for MkDocsは対応しています👍

ビルド

開発中

$ mkdocs serve

localhostとポート番号をアクセスして確認できます。
ファイルを変更すると自動でリロードします。

--dirtyreloadオプションを指定すると、変更時に影響あるファイルだけリビルドします。
見出しが一部バグりますが、それさえ許容出来れば確認速度が上がります。

本番用

$ mkdocs build

siteディレクトリに成果物ができます。

デプロイ

siteディレクトリをpublishして終わりです。

私のサイトではNetlifyを使っています。

[build]
command = "mkdocs build"
publish = "site"

総括

MkDocsを使って、Markdownがメインのサイトを作成するノウハウを紹介しました。

記事内にもあったように、マクロの部分は別の機会で紹介させていただければと思います。

Mimizou RoomにはMkDocsに関する情報も記載しています。

よろしければ覗いてみてください😃