ドキュメントをサイトとして作りたい(静的サイトジェネレーター)
Ctrlキーは小指の付け根概要
何かしらのドキュメントを作って社外等に提供する場合、PDFにすることが多い
しかし、PDFではページの概念があるためレイアウトが制限される。今どき印刷するようなことも少ないので、わざわざページのレイアウトに縛られる必要は無いと感じる。
そもそも作るときにページのレイアウトを考慮して作るのも面倒くさい。
完成形としては、Webサイトの形が良い。左サイドバーにページツリーがあって、右側にページ内の見出し一覧があるような。
そういう形でドキュメントを生成するのは、静的サイトジェネレーターと言われるものでできる。
閲覧するためにはサーバーにホストしなければいけないかもしれないが、そのままhtmlファイル群としてローカルで閲覧できるものもあるかもしれない。
ひとまずいろいろ候補があるので、試していくしかない。
静的サイトジェネレーター
順番はGitHubでスターが付けられている順。 (Honkitはこの中に無い)
Hugo
GOで実装されていて生成が速いとかなんとか。
Docusaurus
Metaが作成したオープンソースのサイトジェネレーター。Reactをベースにしている。
GitBook
クラウドにホストするサービスのようで基本的に有料。GitBook CLIというオープンソースのものもあるが、こちらは開発が止まっているよう。
Docsify.js
静的HTMLファイルは生成しない、と説明があるので、サーバーにホストする必要があるかも。
MkDocs
基本的にサーバーにホストする必要がありそう。
ローカルで見えるようにすることもできるようだが、設定が必要だったり、機能が制限されたりするよう。デフォルトの検索機能を無効にする必要があると記載があったので、検索使えないのは厳しい。サードパーティの検索機能は使えそうな感じだが。
sphinx
Python製のドキュメント生成ツール。いろいろ細かくできるよう。
Honkit
上記のGitBook CLIが開発止まってるのでそのプロジェクトからフォークして作られたそう。
Jekyll
調べられてないけど、AIに聞くと候補として挙がってくる。
まとめ
-
Docusaurusが無難そうな気がする。
→なんかホスティングしないといけないっぽい。
VitePressも基本的にホスティングしないといけなさそう。
これらはReact、VueでSPA的に動くから基本的にWebサーバーで動くことを想定しているよう。 - sphinxは細かくいろいろできて、日本語の情報もそれなりにあったがGitHub上ではそんなに人気が無いのか。
- HugoとMkDocsが可能性ある…？
- Jekyllもいける？