はじめに
MkDocs を使う意味
チェスに関する内容をインターネットで公開する場合 Twitter などの SNS を使用したり YouTube などで動画を公開するなどの手法もありますが、旧来のブログ形式のほうが優れている点もいくつかあります:
- 動画は特に実際の対局を見せたりする場合などは視覚的にわかりやすいが、全部見ようとすると時間がかかってしまう。自分にとって必要な部分だけピックアップして見るようなことも難しい。その点ブログは特にコラムのような内容であれば向いている
- Twitter などの SNS は他者とコミュニケーションを取るには優れているが、文字数制限があったりして長文は難しいし一覧性が乏しい。一つのまとまった内容を見せる場合はブログのほうが良い
ブログを書く場合 Chess.com や lichess にも独自のブログ機能が用意されています。 各システムに強く紐づいている機能のため盤面をシームレスに貼れるなどの便利な機能はあるのですが、現時点で双方とも 記事をカテゴリやタグなどで分類して絞り込んで表示することができない1 という仕様となっています。 チェスプレイヤーであれば、例えば「自戦記」「オープニング研究」「雑記」などと分類したくなるところだと思いますが、それができないということです。 雑多に表示された過去の記事タイトルから探し出すのは一覧性が良いとはいえません。
通常では外部のブログサービスを借りて普通のブログとして書くのが良いでしょう。 IT エンジニア向けの内容になってしまうとは思いますが、ここでは MkDocs という Markdown 記法で書ける静的サイトジェネレータを使用して簡単にこういったドキュメンテーション・サイトを立ち上げる方法について書き残しておきます。
MkDocs は Python で動きますが Python の知識は必要ありません。 コマンドラインから多少のコマンドを叩くことができれば使用することができます。 このサイトが行っているように GitHub を使用すると Markdown ファイルのバージョン管理やデプロイが簡単にできるようになるためお勧めですが、その場合多少の Git (GitHub) の知識が必要となります。
Markdown とは何でしょうか？
Markdown とは文書を記述するための軽量マークアップ言語のひとつです。 Web サイトであれば通常は HTML で記述することになりますが、入れ子になる HTML タグより Markdown で記述したほうが遥かに簡潔なソースとなります。 また Markdown はパーサに解釈されていないソースを人間が直接読んだ時も読みやすいのが特徴です。 以前は Sphinx を使用して reStructuredText2 で書くのが普通でしたが、登場からあまりの書きやすさで瞬く間に Markdown がデファクト・スタンダードの扱いとなりました。
尚 lichess のブログ機能でも Markdown 記法をサポートしており、簡単に文章を装飾させて書くことができます。
参考文献
以下のサイトが参考になるかと思います:
| サイト | 説明 |
|---|---|
| MkDocs 公式 (英語) | 公式サイトなので 1 回は見たいところです |
| Material for MkDocs (英語) | Material テーマのドキュメント。いろいろな機能が使えるのでお勧めです |
| MkDocsによるドキュメント作成 | 日本語の詳細なリファレンスなので目を通してみましょう |