静的サイトジェネレータ (SSG)

ドキュメンテーションに利用できる静的サイトジェネレータ（Static Site Generator）について調べている。まだまだ道半ばであるが、ある程度まとまってきたので現時点の資料を公開する。（今後も追記予定。）

要件

少なくとも以下の機能があるものを調査対象とする。

• Markdownでの記述
• デザイン（テンプレート）切り替え
• ページ階層（折り畳み対応ナビゲーションバー、パンくずリストの表示）
• ページ内検索
• 多言語化（できれば翻訳文言の管理）
• ソースコードのシンタックスハイライト、ダイアグラムの表示（MermaidJSなど）
• ローカル（Webサーバーなし）での参照

候補

少し検索してみただけでも多くのプロダクトが出てくる。詳細は調べられていないが、有名どころは以下の通り。

• Hugo
• Docusaurus
• MkDocs
• VuePress
• Sphinx
• Pandoc

参考

• Static Site Generators - Top Open Source SSGs | Jamstack
• Our Top 11 picks for Static Site Generators (SSGs) in 2021 | Hygraph
• ドキュメント作成に向いている静的サイトジェネレータはどれ？ - Wiz テックブログ

Hugo

Go言語で実装されており、高速な動作を謳い文句としている。

インストール

Windowsの場合はScoop (もしくはChocolaty) でインストールするのが簡単である。

scoop install hugo

参考：Install Hugo

プロジェクト作成～ビルド

Quick StartのStep 2: Create a New Site～Step 7: Build static pagesの通りに進めればよい。

プロジェクトのディレクトリ構成

代表的なディレクトリは以下の通り。詳細はDirectory Structureを参照。

ディレクトリ	説明
archetypes	新しいcontentを作成するときのテンプレートを入れる。
content	サイトのcontentを入れる。直下のディレクトリがContent Sectionとなる。
layouts	home page, list page, single pageなどの各ページ用のテンプレートを入れる。
public	ビルド結果の出力先

Contentの管理

サイト構造

contentディレクトリの構造がサイトの構造に反映される。

content
├── _index.md          <-- homepage (https://example.com/)
└── posts              <-- section (because it is the first-level directory)
    ├── first.md       <-- single page (https://example.com/posts/first/)
    └── tech           <-- section (becuase it contains _index.md)
        └── _index.md  <-- list page for section (https://example.com/posts/tech/)
        └── second.md  <-- single page (https://example.com/posts/tech/second/)

参考

• Organization of Content Source
• Path Breakdown in Hugo
• Content Sections

Taxonomy

Contentをグループ化するための分類機能。

Site Configにて分類（Taxinomy）の一覧を定義する。

[taxonomies]
  tag = 'tags'

Front Matterにて、各分類についてContentが属するグループ（Term）を定義する。

tags = ['Development', 'Go', 'fast', 'Blogging']

多言語化

Content File (/content/**)

コンテンツの翻訳を管理する方法は2つある。（参考：Translate Your Content）

• article.en.md、article.fr.mdのようにファイル名の接尾辞に言語コードを入れる。
• /content/en/about.md、/content/fr/about.mdのようにディレクトリ名に言語コードを入れる。

Layout File (/layout/**)

layout内のテンプレートを多言語対応するには i18n/{言語コード}.toml に記載した翻訳文言をi18n関数（{{ i18n "home" }}のような記述）で参照する。（参考：Translation of Strings）

モジュール

Hugoはstatic、contentなどのコンポーネントをモジュールにまとめて、自由に組み合わせて利用できる仕組みとなっている。モジュールの実体はGo Moduleで動いているとのこと。

管理用のCLIコマンド（hugo mod xxx）が用意されている。Moduleの設定はconfig.tomlのimports以下に記録される。

参考：Hugo Modules

ドキュメンテーション用テーマ

Docsy、Book、Learnなど様々なテーマが公開されている。

参考：Twelve Amazing Free Hugo Documentation Themes | CloudCannon

Docsy (Hugoテーマ)

技術文書向けのHugoテーマ

インストール

(1) Hugo Moduleとして追加、(2) Git submoduleとして追加、(3) ファイルコピーで追加 の3通りの方法がある。Docsyのバージョンアップのことを考えると、(1) Hugo Moduleを使うのが賢明である。

参考

• Installation options
• Update Docsy

Hugo ModuleとしてDocsyを使うには自力でモジュールを追加する方法の他に、プロジェクトのひな形をコピーする方法もある。後者の方がコンテナで動かすためのdocker-composeファイル等も含まれるため、簡単である。

参考：Use Docsy as a Hugo Module

ドキュメントをプレビューする

Windowsの場合は、コピーしたひな形プロジェクト（Docsy example site）をVisual Studio Code (WSL) で開き、以下でコンテナを起動する。

docker-compose up

コンテナ内でhugo serverが実行され http://localhost:1333 にアクセスするとライブプレビューを見ることができる。

参考：Running a container locally

ドキュメントをビルドする

プレビューをバックグラウンドで動かしたまま、同コンテナでビルドを実行するか、

docker-compose up -d
docker-compose exec site hugo

コンテナを起動してhugo buildを実行すればよい。

docker-compose run site build

publicディレクトリにビルド結果が保存される。

ローカルで参照可能なファイルをビルドする

デフォルト設定でビルドすると、ビルドしたファイルをローカルで直接ブラウザで開いても、リソースの読み込みやページ間のリンクが上手く動かない。ローカルで動くようにするには下記の設定をconfig.tomlに入れればよい。

relativeURLs = true
uglyURLs = true

relativeURLsをtrueにすると相対パスになり、uglyURLsをtrueにするとリンクを出力するときにファイル名（index.htmlなど）を省略しなくなる。

参考

• How can I force HUGO to generate relative paths for everything? - support - HUGO
• How to make hugo generate links with "/index.html" instead of simply "/" by the end of the link - support - HUGO

ページ内検索の設定を変更する

Google Custom Search Engine、Algolia DocSearch、Lunrのいずれかを利用できる。LunrはJavaScriptでのローカル検索のため、非公開サイトでも利用可能である。（ただし、ビルドしたファイルをブラウザで参照する場合は動作しない。）

参考：Site search options