Mkdocs: 静的サイトジェネレータ

色々とお遊びをしていると、備忘録を作るんですが、設計図?とかは作図が面倒なのでその場で手で書いて、写真を取ったりして残しています。

Markdown記法:

　その中で、お遊びの環境つくりとしてPCでソフトウェアをいじりますが、インストールの方法や設定のメモをこの頃はMarkdownという記法で作ったファイルにしています。忘れるので、備忘録として書いてるだけなんですが、、。(よく調べてはいませんが、HTMLは、HyperTextMarkupLanguage、でMarkUpなんですが、こちらはMarkDownです、、、)

　HTMLの小うるさい(ごめんなさい)タグの山を使うのではなく、PlainTextに簡単な(10個も覚えれば十分)構文を覚えればすぐに、MarkUpされたドキュメントに変換してくれます。Markdown関連はこちらからググってください。

　例えば、"# "(#とspace一個)を行の先頭につけると、一番大きな見出し行に。"## "とすると次に大きな見出し、、、。"- "([-]とspace一個)とすると、以下箇条書き、"1. "([1]と[.]とspace一個)とすると項番付きの箇条書き、とか。表もフローチャートも作れます。

　ほぼ、通常のTextファイルなので、もちろんPlainTextとしても読むことができます。

Markdown記法用Editor:

　Markdown記法を適用したEditorもいくつかありますが、私は、いくつか試した中で"Typora"(Windows用)を愛用しています。リアルタイムで整形してくれるので、ワープロを打っている感覚でドキュメント作成ができます。(Wordとかよりも、少ない手数で簡単に「それなり」の文書にすることができます。)

　HTMLにも変換してくれるので、HomePageにもすぐに使えます。Chromeブラウザの拡張機能で、Markdownファイルを整形してくれるものもいくつかあるので、それをインストールするとブラウザでも見られます。

　Typora、有償アプリに移行してしまったので、今度は、OSSの”Mark Text"というのに乗り換えました。使い勝手はほぼTyporaと同じです。（＠2022/3/6追記)

　で、メモを色々溜め込んで来たら、昔のメモを検索したり表示したりしたくなります。と次に続く、、。

静的サイトジェネレータ:Mkdocs

　自分のPCでフォルダごとに階層表示したり、検索できればよいので、なにか良いものは無いか、と探していたところ、「Mkdocs」というものを見つけました(Mkdocs自体についてはMkdocsのページを御覧ください。日本語でも探すと色々出てきます。例えばQiita等でMkdocsを検索すると色々と出てきます)。もともとは、表題にある「静的サイトジェネレータ」という部類のWEBの画面?を作るもので、これは「静的」なので、アクセスした人の要求に応じてDBなどからダイナミックに画面を変更して表示するわけではなく、主にソフトウェアのドキュメントを表示するような用途に向いているものだと思います。もちろん日本語のファイル、日本語ファイル名に対応しています。

Mkdocs動作環境:

　「Mkdocs」は、はやり?のPythonのモジュールとして配布されているので、Pythonを載せて、起動します。私はMkdocs/Python3/Miniconda/WSL2/Windows10の環境とMkdocs/Python/Docker/WIndows10でも動作させましたが、Windows10に直接Pythonを載せての実行も可能だと思います。(自分ではやってませんが、、)

　これが良いところは、Markdownで作ったファイル/修正したファイルをその場でそのままOnTheFly(数秒の時間は必要ですが)で、自分のPC上の簡易WEBserverで見られる、という部分です。修正したものがすぐにWEBブラウザで見られるのは嬉しい機能です(この機能はあくまでも確認用なので、公開する場合は、きちんとしたWEBserverを準備して、と記載されています)。

　あとは、bashやら、pythonやら色々な言語をサポートしているので、コマンドなどを貼ることできて、キーワードに着色してくれたりとソフトを書く人にはわかりやすいです。

　あと、規定したフォルダ以下においてあるMarkdownファイル(extensionが"md")を全検索して自動的にリスト化してくれる機能も素敵です。適当にフォルダに突っ込んでおけば検索対象になります。

Theme: Mkdocs-material

　テーマ(Theme)もいくつかありますが、皆さん使われているのは、materialというThemeで、多分見ていただくと、softwareのmanualなどどこかのWEBpageでご覧になったことがあるのではと思うくらい使われているような気がします。例えば、 NodeMCU/ESP8266のドキュメントページも多分Mkdocsだと思います。

　割と簡単にインプリできますので、ご興味を持たれた方は、是非Tryしてみてください。

MkdocsのVersionについて:

　Mkdocsのversionの1.2.1は、unicodeを使ったファイル名やパスの部分にbugがあるので、2021/7/22現在の最新、Mkdocs version1.2.2(2021/7/18リリース、出たばっかり!!)、をお使いください。version 1.2.1では、1.1.2では使えた漢字ファイル名が使えなくなり、色々となにかしくじっているかな、と調べたのですが、1.2.2のリリースノートを見たら、file/pathのunicodeの部分のbugを潰した、と書いてあったので、やってみたら修正されていました。

お楽しみください。

Keyword: Markdown記法, Typora, Mkdocs, Mkdocs-material