StaticGenというサイトでいろいろと紹介されていますね。
好みのものを選ぶと良いのですが、通常のブログと違い、運用に手間がかかります。 個人的に、Jekyll、Pelican、Middleman、Sphinx、MkDocs（当サイト）を使ってみて どういう考え方でジェネレーターを選ぶか気の向くまま書いてみようと思います。
環境構築/機能面
次の4つが円滑に使用できない、もしくは実行できない、ようなジェネレータは 書くコストを高くするだけなので利用しないほうが良いと思います。
| 項目 | 利用目的・内容 |
|---|---|
| 環境構築 | パッケージのインストールなど |
| Hot reload | 自動更新 |
| Build | サイトのジェネレート |
| Deploy | サイトのホスティング |
また、これを拡張機能を使って実現できるジェネレータは個人的には今現在避けています。 デフォルトで動くってやはり素晴らしいです。
環境構築
サイトのジェネレータが依存しているパッケージやモジュールが、 自分にとって不親切なもの、わかりにくいものは避けましょう。 本来の目的は文章を書くことです。 ジェネレータの依存関係を解決することではありません。
また、OSSなどでドキュメントを他の人が書き換える場合がある場合、メンテナスしやすいようにコマンド1つで立ち上がるようにしておくべきです。
Cirlcle CIのドキュメント(circleci/circleci-docs)を修正したときはちょっと感動しました。なぜならば、docker-compose upのみで自分の環境に出来上がったからです。
とても小さな修正でしたが、このお陰でスムーズにコントリビュートでき、とても印象的だったのを覚えています。
Live reload
後ほど出てきますが、シンタックスハイライトなどの確認や、木構造の確認、リンクが正しく配置されているか書くにする時に非常に大切です。些細な事は全体を見て初めて分かることもあるので常に確認できるような環境が整っている方が望ましいでしょう。
Build
たまにあるのですが、live reloadで見ているときは正常に動いているけれど、Buildするときにエラーが出てつまづく、なんと事があります。 さくっとBuildできるようなジェネレータが望ましいです。
Deploy
最近だと、netlify.comにホスティングするのが主流になってきたでしょうか。
僕が知っているnetlifyは無料で認証つけてくれた時代ももあったのですが、今は結構お金取りますね。。。
脱線してしましました。
一般公開ベースだと、githubかnetlify当たりにホスティングするかと思います。
netlifyにホスティングするならばデフォルトでサポートしているものを選びましょう。
githubだと、travis回しても良いのですが、docs/配下に生成しておけば良いので、
生成場所を設定でさくっと切り替えられるようなものを選んだほうが良いでしょう。
少し進んだことをすると、認証（Basic認証や、oauth2_proxy）をかけたいが、コストを抑えたい場合はHeroku Container Registryなどを使うと経済的かと思います。
ディレクトリ構成、ファイル管理
文章を書きたいだけなのに、CSSとかJavaScriptとか、設定ファイルとかがゴニョゴニョあるのは、目の毒です。 それと、ついつい中身をいじりたくなってしまうので、極力無い方が良いです。
画像やPDFといったメディアはどこから読み込み込めるか？
(個人的な)結論から先にいいます。 静的サイトジェネレータを使用して画像を配置したりする場合、 文章を記述しているMarkdownのファイルと同じ階層か、深掘りが可能な階層にメディアが 配置できたほうがよいです。
理由は本当に単純で、別のサイトジェネレータに移行した場合や、メディアの差し替えを行う時に、 どれだけ早くできるか、を考えた時にMarkdown内に書かれている相対パスと実際のディレクトリの相対パスが 一致している方が圧倒的に移植性が高いです。
Good
例えば、次のようにファイル構成があったとき、hello.md内で画像を呼び出したい場合があるとします。
hello.md
media/image.png
いま、ここで推している参照方法は、次のように相対パスで呼び出せる方法です。
Bad
Badなパターンは次のような構成です。
src/docs/hello.md
/assets/img/image.png
Markdown中の記述は次のように書きます。
このような場合は最悪です。ルートディレクトリから始まっている場合はサイトジェネレータのホスティングの都合を押し付けられているため、文章を書く妨げになります。 管理が大変です。
モチベーションを下げる原因になるので、このようなサイトジェネレータを選ぶのは避けたほうが良いでしょう。
拡張機能
どんな拡張機能でも、1分以内に追加できるもの・仕組みである方がいい。 だって、拡張機能のためにドキュメントを読みだすと、脱線しちゃうもの。
Syntax Highlight / Code Highlight
特に、エンジニアなら、コードを書くのでコードハイライト (highlight.js, prismjsあたり？）が後からとても簡単な設定で導入できると嬉しいと思う。 また、テーマの色も簡単に変えられるものを探したほうが良い。
サイト内検索機能
技術的なブログを書いたり、メモ代わりにするなら検索機能は必須だと思う。 あるものを探したほうが良い。
タグ
あるに越したことはないと思うが、個人的にはなくても良いと思っている。 （SEO的にはあったほうが良いのかもしれないけれど） 理由は単純で、管理が大変だからです。静的サイトジェネレータの性質上、全て自分で書いていくのです。 いちいち、どんなタグを付けるかを考えるより、どのディレクトリの下にこの文章を配置しようか、 を考えたほうがよっぽど大切です。
長く静的サイトジェネレータを利用していくならば、ディレクトリの切り方を長く見据えて構築した方がいい。 また、代替のジェネレータはディレクトリのURIがサイトのURLに反映されるので、そこまで頑張ってタグをつけなくてもいいでしょう。
タグで検索するぐらいだったら、サイト内検索がしっかりとしたものを探したほうがよっぽどマシです。
日付
日付は非常に大事です。Googleにインデックスされる日付のはMarkupされたものじゃないので、そこは気にしなくていいんですが、サイト内には流石に表示したいですよね。 が、かなりのサイトジェネレータが手動でつけていくようになっています。
個人的には、gitのコミットログだったり、ファイルの作成日と更新日から自動的に取得して、ビルド時に自動的に入力してくれると、その管理工数が減るので非常に楽です。まだ、そのような拡張機能に出会っていないので、実はあるよ、なんてあれば教えてください。
MarkdownのExtension
個人的には、pymdown-extensionsが好みだ(pypi, Document)。この拡張機能のドキュメントはmkdocsで作成されている。超クールなテーマのMaterial for MkDocsを利用している。 Extensionsが素晴らしいのでぜひ見て欲しい(mkdocsのステマ)。
ただ、Markdownの拡張機能を入れると、それ以外のツールでは再現できないなどの不具合も生じてしまう。 しかし、pymdown-extensionsの記法が独特かと言われるとそうでもなく、reStructuredTextで見られるようなディレクティブをMarkdownに落とし込んだ形になっている。
reStructuredTextについて
大学時代のドキュメントはSphinxで書いてきました。 理由は単純で、TeXを使っている、かつ研究室内のサーバーにウェブドキュメントとしてホスティングすることで誰もが簡単にドキュメントにアクセスするためです。 電子機器を持ち込めないような場所は紙で印刷する必要もあったため、SphinxのPDFエクスポート機能にはだいぶ助けられました。 TeXで数式を掛けるところからも非常に役にたちました。
特に、ディレクティブが優秀で、後からclassをつけたり、画像のサイズ変更したりでき、
目次ツリーや、includeでファイルを分割できるところも非常に活躍しました。
だけれども、最近のエディターではMarkdownのサポートが主流で、reStructuredTextの記法で書いているドキュメントは、ちょっと（数年）前Pythonのライブラリ系ぐらいしか見ない。
使い勝手の面からしてもMarkdownのほうが便利だったため、 PyPI用のドキュメントを書く以外では、最近ではなかなか使っていません。
フォント
テーマ単位でフォントが決まっているものが多いですが、自分の気に行ったフォントを選びましょう。
私個人としては、単純に読めるフォントをお勧めします。
アニメーション
凝ったアニメーションはドキュメントには不要と思っています。 WEBの情報は流して見るものですから、さっさと切り替わって目的の情報さえ得られればよいです。
最後に
このサイト、iframeで構成されています。SPAのデバッグモードじゃないですよ？
こういうの、嫌いじゃないです。むしろ好きです。