mkdocs の導入
mkdocs の導入
どうもすぐ忘れるので書く。これは n 次情報もいいところなので注意。
Windows で Anaconda を利用すること、すでにインストールされていることを想定しています。
conda のパスを通してなければ Anaconda Prompt かなんかを開きます。通してあるなら cmd を開く。なんでもいいです。
powershell だと activate がなんかややこしいので cmd にしています。
仮想環境の準備（ご自由に）
mkdocs を使う仮想環境を作ります。
> conda create -n mkdocsenv
activate します。
> conda activate mkdocsenv
プロンプトがこんな感じになります。
(mkdocsenv) >
入っているモジュールの一覧を表示してみます。
(mkdocsenv) > conda list
おそらく mkdocs は入っていないのでインストールしていきます。モジュールを検索してみる。
(mkdocsenv) > conda search mkdocs
おそらくここには mkdocs はありません。正確にはこのチャンネルにはありません。
別のチャンネルも含めて検索します。
(mkdocsenv) > anaconda search mkdocs
conda-forge 等のチャンネルにあるような表示が出てくるはず。チャンネルを指定して mkdocs をインストールします。
(mkdocsenv) > conda install mkdocs -c conda-forge
mkdocs そのものと mkdocs に依存関係のあるモジュールが一括でインストールされます。
コマンド conda list で確認できます。
仮想環境の準備は以上。Anaconda Prompt はビルドするときに使うので、閉じないで開いておきます。
サンプルを作る
適当にフォルダを作ります。
フォルダの root に mkdocs.yml ファイルを作ります。
mkdocs.yml
site_name: my page
site_name は必須項目のようす。（設定項目については公式ドキュメント参照）
フォルダの root に docs フォルダを作ります。
docs フォルダにとりあえずサンプル用の index.md ファイルを作ります。
docs/index.md
# Sample hello mkdocs
仮想環境の準備で使った Anaconda Prompt でこのフォルダに移動します。
(mkdocsenv) > cd 'フォルダのパス'
ビルドします。先述の仮想環境を activate しておく必要があります。そのために Anaconda Prompt を開きっぱなしにしておきました。
(mkdocsenv) > mkdocs.exe build
フォルダの root に site というフォルダが作られます。この中にビルドの結果生成されたファイルがいろいろ入っています。index.html がきちんと生成されているはずです。
サーバーを立てて index.html にアクセスするか、単純に index.html をブラウザで開くか二通りあります。この辺りのことは別の場所に書く。
ひとまず以上で必要最低限は終わり。しかし、毎度毎度ビルドのために cmd 開いたり仮想環境を activate するのは面倒なので次に説明する方法で簡略化します。
vscode でビルド環境づくり
先ほどのフォルダを vscode で開きます。
vscode のバージョンによってボタンの位置が少し異なりますが「ターミナル > タスクの構成 > ... > Others」と選ぶと、.vscode フォルダが root に作られ、その中にtask.json が自動生成されます。(こんなに詳しく書く必要があるか？とも思うけど、初めての人間にとってはそれくらいでいいのだと思ったりする。まあ、そんな人間が mkdocs に辿り着くとも考えにくいが。)
task.json を次のように書き換えます。
{ // See https://go.microsoft.com/fwlink/?LinkId=733558 // for the documentation about the tasks.json format "version": "2.0.0", "tasks": [ { "label": "build", "type": "shell", "command": "${env:localAppdata}\\conda\\conda\\envs\\mkdocsenv\\Scripts\\mkdocs.exe build", "group": { "kind": "build", "isDefault": true }, "problemMatcher": [] } ] }
以降はショートカットキー「ctrl + shift + B」を押すだけで一発ビルドすることができます。他の何も必要ありません。簡単！ステキ！！
参考:
