MkDocsて結局、何をするやつだっけ？
GitHub Pagesをなるべくラクにつくりたい
作業をすすめるうちに、githubにアップしたソフトウェアの情報をとりまとめていく必要が出てきました。
githubのwikiを使おうかpagesを使おうか迷っていたところ、MkDocsで作成したというサイトの雛形をいただいたので、続きを作るべく使い方を調べてみることにしました。
使い方や機能の概要、また更新作業について、忘れそうなので自分向けのメモにまとめました。設定や機能の詳細については、別のサイトをご参照ください。
MkDocsは変換ツール
MkDocsは一体何をどこまでしてくれるアプリでしょうか？
ズバリ、以下のことができます。
- マークダウン形式で書かれた.mdファイル群を、よき感じにWEBサイト用のファイルに変換してくれる。
- テンプレートでデザインを選べる。
- 変換結果はすぐに手元のブラウザで確認できる。
- .mdファイルの書き換えると、同時にブラウザの表示も即時更新される。
- 完成したファイルをgithubにアップロードする機能もある。
といった感じです。.mdのルールで書いていくので、ページ数が多い場合などに効率的にサイト更新を行うことができます。
導入方法などの概要は下記などが参考になります。
アプリのコードがpythonで書かれているのも特徴のひとつです。どの機種でも使うことができます。
MkDocsの作業の流れ
おおむね以下のような作業行程があります。
① mdで書かれたファイル群を準備する。
② $ mkdocs new ＜任意のパッケージ名＞ のコマンドでプロジェクトを作成する。
③ docsフォルダの中に、mdファイル群を入れる。
④ 変換設定などが書かれたyamlを編集する。
⑤ index.htmlを編集する。
⑥ $ mkdocs build でファイルを変換する。
⑦ $ mkdocs server のあとブラウザで結果を確認する。
⑧ 変換結果はsiteフォルダに入る。
⑨ ブラウザを見ながらmdを書き換えて更新し、微調整する。
⑩ 改めてbuildを行い、結果をgithubにアップする。
.mdファイルを書き換えただけで、サイト用の変換結果がすぐに確認できるところが便利です。
作業はノートPCで、表示結果をHDMIで接続したPCモニタにしたりすると作業がしやすいかもしれません。
一度アップロードした後の情報更新については、⑨⑩の行程を繰り返して作業することになると思います。
GitHub Desktopでアップロードする
MkDocs自体にもGithubにアップロードする機能がありますが、
今回はGUIで作業しやすいように、GitHub Desktopでアップロードします。
GUIでのアップロード手順
① GitHub DesktopにGitHub Pages用のリポジトリをクローンする。
② MkDogsのbuildによって生成されたsiteフォルダ内のファイルを、クローンしたリポジトリにコピペする。
③ GitHub Desktopでプッシュすればアップロード完了。
Github Pagesでチェック
Github Pagesのサイト名は「https：//名前.github.io/リポジトリ名」という形になります。Github Pagesをアクティブにするには、下記が参考になります。
なかなか便利でした
内容の分量が多いサイトを作る場合などに、とてもよい方法だと感じました。
細かい点でわからない部分も多々ありますが、ブラウザ上での情報更新が可能なwikiと比べても、こちらの方がサイトの画面がスッキリしている分よさそうです。