したメモ。
以前 WinHelpをMarkdownにして編集しやすくする - koudenpaのブログ したのだけれど、単にMarkdown変換しただけだと閲覧性がイマイチで、結局 chm 変換したファイルをローカルで眺めていた。
いちいちローカルでファイルを開くのが面倒くさいし、元々編集性と閲覧性を上げたくて変換したのに編集結果を眺めていないのでは目的を達成していない。
というわけで何かしらのSSGを試したかったのでMarkdownを元にWebサイトにしてみた。
構成
Jekyll + Azure Static Web Apps
Jekyll なのは、そのうちGitHub Pagesにしたいと思ったときに簡単に移植できるようにしておきたいから。
Static Web Appsなのは、慣れていることに加えてビルドシステムがJekyllに対応しているから。
このチュートリアルに従えば素直にMarkdownを元にSSGしてサイトを公開できた。
こんな感じ。
簡単だし、PRでそのPR内容を確認する環境が勝手に生えるように構成されるし、独自ドメインの証明書も自動更新される。全般に体験が良い。
静的サイトをお手軽に公開するにはStatic Web Appsはそれなりにおススメ。他のホスティングサービスあんまり知らないので積極的におススメという感じではないけれど、AzureでBlob Storage + CDNを使うよりは格段に楽で便利だと思う。
- Project: https://github.com/7474/SRC/tree/master/SRC.Sharp.Help
- CD: https://github.com/7474/SRC/blob/master/.github/workflows/azure-static-web-apps-yellow-pebble-0ddb1c400.yml
Just the Docs テーマのメニューを力業でカスタマイズ
テーマには Just the Docs を使ってみた。
ホスティング対象がヘルプであるという性質上検索機能が欲しかった、元のヘルプの閲覧同様のツリー表示のメニューが欲しかった、辺りの要求を満たすテーマをテーマギャラリーから（どのギャラリーを使ったかは忘れた）から検索してそれっぽいのを選んだ。
ちょいちょいOSSのドキュメントで見かけるテーマであることもあって、メニュー、検索両面で機能感は十分だったけれど、既定ではメニューにはディレクトリ構造が反映されるので各ページがフラットに配置されている現状にマッチしなかった。メニューをカスタマイズする場合のコレクション機能を覚えるのはなんか面倒くさそうだった。
ので、希望するメニュー構成のデータファイルを書いてそれを元に強引にメニューを構築してしのいだ。
メニューのテンプレートを複製して、いい感じにレンダリングする独自テンプレートを作って、それをインクルードした。
結果それっぽいメニュー表示ができた。
取り合えず望む出力を得たいだけなら、このくらい強引な手法でもいいと思う。
そんな感じ。
Webブラウザで見られるようになって便利になったし、更新したら反映されるのでヘルプ整備していくかって気になってよかった。
