技術メモを旧GoogleサイトからHugo + Docsyに移行している話

TL;DR
はじめに
移行先システムの選定
- Docsyについて
- 他に検討したツールとNG理由
  - Hugoテーマ「LEARN」
  - GitBook
Docsyによるサイト構築
- Docsyのセットアップ
  - hugoの拡張版をインストール
  - デモサイトのソースを雛形としてクローン
- コンテンツ作成の準備
GitHub Actionsによるデプロイ自動化
まとめ

TL;DR

できたサイトはこちら: https://progrhy.me/tech-notes/

コンテンツは2020-04-26現在、全く移行できていません。

はじめに

4年以上前から、雑なメモを公開しつつストックするサイトとして、Googleサイトを使ってきました。*1
技術メモサイトのURLは https://sites.google.com/site/progrhymetechwiki/ です。

GoogleサイトのWYSIWYGエディタは特に好きではありませんが、Markdown Hereというブラウザ拡張を使うとMarkdownで書けるので、問題ありませんでした*2。

Googleサイトの良い点として、ブラウザだけで作業ができるので環境構築が不要である点や、ビルド・公開といった手間が不要という点が挙げられます。

一方で、問題点がないわけではありません。

旧Googleサイトは来年末に終了が予定されている。
各ページをMarkdownファイルで管理しているわけではないので、他のMarkdownベースの文書管理システムに移行しづらい。

特に、前者がクリティカルです。

「新しいGoogleサイトに移行すればいいんじゃないの？」と思う人もいるかもしれませんが、変換ツールは上手く動かず、新GoogleサイトでMarkdown Hereを試したところ、上手く動きませんでした。

そこで、旧Googleサイトの終了がアナウンスされた頃から「移行しなければならない」と思っており、今回、ようやく実施に漕ぎつけました。

移行先システムの選定

移行前の技術メモサイトを見て頂ければわかると思いますが、結構ジャンルが多岐に渡っており、ページ数が多いです。*3

それも踏まえて、私が移行先システムに求める要求は以下の通り:

3以上のレベルでページを階層構造にできる
ページツリーをサイドバーなどで俯瞰できる
記事の目次を表示できる
記事の全文検索が可能
Markdownファイルで記事を管理できる
Markdownで以下の拡張記法がサポートされている
- テーブル、シンタックスハイライト
ページ数が多くなっても、待てる時間内でビルドが終わる

数年前だとなかなかいいツールが見つからなかったのですが、最近はだいぶ選択肢が増えているように思います。

HugoやJekyllなどの静的サイトジェネレーターなら、上の要求の大半は満たされます。
ただし、「3以上のレベルでページを階層構造」にして「ページツリーをサイドバーなどで俯瞰できる」ようなテーマは限られているかと思います。
Hugoは高速なので、ビルド時間に関してアドバンテージがあるでしょう。

結論としては、タイトルに書いたようにHugoのDocsyというテーマを使うことにしました。

Docsyについて

DocsyはGoogleが去年の7月頃に公開した（*4）HugoのThemeで、特定の製品に関する技術文書の作成に向いています。
Kubeflow, Knative, Apache Airflowなどのドキュメンテーションに使われています。

以下のような機能があって、だいぶリッチなツールです。

多言語対応
対象製品のバージョニング対応
ランディングページ
複数方式の全文検索
フィードバックの送信
記事の編集リンク、GitHub Issue作成リンク

やや牛刀感があるほどでしたが、以下のような点が決め手になってこれを選びました:

ルック&フィールが良かった
ページ編成の自由度が大きい
Google発OSSでアクティブに更新されており、複数の著名なソフトウェアで使われており安心感がある
Hugoなので速い
私がHugoに慣れている

他に検討したツールとNG理由

Hugoテーマ「LEARN」

https://learn.netlify.app/en/

これは以前、当ブログでも紹介しました。

Hugoのイケてるドキュメンテーション用Theme "Learn"と"DocDock" - progrhyme's tech blog

当時から当たりをつけていたテーマだったので、最初これで構築していたのですが、ページ階層が増えてきたときにchapterページ（セクション見出しページ）のレイアウトが気に入らなくて中断しました。

いま思うとレイアウトをカスタマイズする手もあったし、上の記事で紹介した「LEARN」のforkである「DocDock」を使う手もあったな、とは思います。

GitBook

https://www.gitbook.com/

これはご存知の方も多いと思いますが、Hugoなどと同様にMarkdownでソースを管理して、HTML/PDF/ePUBなどの形式で出力できる文書作成ツール / プラットフォームですね。
これまで触る機会がなかったのですが、要求をある程度満たしていると思ったので試してみました。

機能的には問題なさそうでしたが、将来的に以下の点が問題になりそうだと思って、止めました:

GitBookは今後、プラットフォームサービスに注力していくそうで、OSSツールチェインはdeprecatedになっている。*5
ページ数が多くなると動作が重くなるらしい*6

Docsyによるサイト構築

Docsyのセットアップ

https://www.docsy.dev/docs/getting-started/ の手順に相当します。

hugoの拡張版をインストール

DocsyではSCSSを使っているので、hugoの拡張版が必要です。
作業時はUbuntuマシンを使っており、snapでhugoをインストールしていたので、snapで更新するのが簡単でした。*7

snap refresh hugo --channel=extended

デモサイトのソースを雛形としてクローン

hugo new site コマンドでゼロからサイトを作っていく方法もありますが、Docsyはやや独特な構成をしているので、動いているサイトをベースにした方が早いだろうと思いました。

git clone https://github.com/google/docsy-example.git tech-notes
cd tech-notes
git submodule update --init --recursive

※themes/ 下にsubmoduleとして取得されるDocsyテーマ自身もsubmoduleを含んでいる（*8）ので、 git submodule update コマンドに --recursive オプションが必要です。

この後、 hugo server コマンドでデモサイトがローカルで動きます。

サイトをビルドする場合、先に npm install が必要です。

npm install
hugo

コンテンツ作成の準備

不要コンテンツの整理とコンフィグ調整

元のデモサイトのコンテンツで、要らないものを削除していきます。

以下、リンク先はGitのコミットログです:

日本語をデフォルト言語として、他の言語を削除
- content/en -> ja にリネームして、 content/no を削除
デモサイトから不要なコンテンツの削除
- content/ja/{about, blog, community}/
- content/ja/docs は _index.md のみ残して削除
config.tomlの内容調整

見た目の調整

https://www.docsy.dev/docs/adding-content/lookandfeel/ に従って、テーマ色の変更と、ランディングページの背景画像を変更しました。

layoutsのカスタマイズとdocsのパス変更

更に、以下の対応を行いました。

フッターに「Powered by Docsy theme of Hugo」を追加
右サイドバーからGitHubイシュー作成リンクを削除
~~テーマの layouts/docs をプロジェクトの layouts/a としてコピーし、~~ content/ja/docs -> a にリネーム
- （4/27追記） layouts/a -> ../themes/docsy/layouts/docs のsymlinkに変更

最後の対応は、そのままだと記事のURLが https://progrhy.me/tech-notes/docs/ となり冗長に感じたために行いました。 a に意味はありません。

できれば a よりも _ にしたかったのですが、ローカルでは正常に表示されるにも関わらず、publishするとなぜかNot Foundになってしまうので諦めました。*9

以上で、後はどんどん記事を作成していくだけ、という状態になりました。