Hugoでマニュアルを作る #1 インストールから最初のドキュメントまで

フレームワーク Hugo Documentation Static Site
読了 5分

ドキュメントを本格的に作り始めると、ほぼ例外なく同じ問題に出会います。README 一枚では手に負えないドキュメントをどこに積み上げるのか、という問題です。Notion は外部公開とバージョン管理が面倒で、ブログツールで作ると記事が時系列に並ぶだけでリファレンスとして使いづらいです。そこで多くのチームは、ドキュメントをコードのように扱う方式、つまり Docs as Code へ移っていきます。マークダウンで書き、Git で管理し、静的サイトとしてデプロイする方式です。

このシリーズは、その最初の一歩である 静的サイトジェネレーターでドキュメントサイトを建てる方法 を扱います。ツールは Hugo です。Go で作られた単一バイナリなのでインストールが軽く、数百ページでもビルドが1秒前後で終わります。テーマはドキュメントに特化した Hextra を使います。

今回のシリーズは Hugoでマニュアルを作る の全6回です。

  • #1 インストールから最初のドキュメントまで ← この記事
  • #2 サイドバーと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、コールアウト
  • #4 Cloudflare Pages でデプロイしてドメインを接続する
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索インデックス、アクセシビリティ、ドキュメント文化

この記事では Hugo が何を準備物として要求するのか、そして 新しいサイトを作って Hextra を接続し、ローカルで最初のドキュメントを表示するところまで を実際に実行しながら締めくくります。

準備物の三つ #

Hugo ドキュメントサイトは、まず三つのツールをインストールする必要があります。

  1. Hugo Extended — Hugo には通常版と Extended の二つがあります。Hextra をはじめとする最新テーマは内蔵のアセット処理機能を使うため、必ず Extended をインストールする必要があります。
  2. Go — Hextra は Hugo Modules で配布されます。テーマをダウンロードして更新するのに Go が必要です。
  3. Git — Hugo Modules が内部的に Git を使い、どのみちドキュメントを Git で管理することになるので一緒に準備します。

Hugo のインストール #

OS ごとのコマンドは次のとおりです。

インストール (macOS / Windows / Linux) 
# macOS (Homebrew)
brew install hugo go git

# Windows (winget)
winget install Hugo.Hugo.Extended GoLang.Go Git.Git

# Linux (例: Debian・Ubuntu 系はディストリビューションのパッケージが古い場合が多いため
# 公式リリースバイナリのインストールを推奨)
sudo apt install golang-go git
# Hugo Extended は GitHub リリースの hugo_extended_*.deb をダウンロードしてインストール

インストール後、バージョンを確認します。出力に extended が含まれている必要があります。

バージョン確認 
hugo version
# hugo v0.xxx.x+extended ... のように extended の表記を確認
go version

extended が見えなければ通常版がインストールされているので、Extended で入れ直さないと次の段階で詰まります。

新しいサイトを作る #

空のサイトを一つ作成します。設定ファイルの形式は読みやすい YAML に指定します。

新しいサイトを作成 
hugo new site my-docs --format yaml
cd my-docs

作成されたフォルダで Hugo Modules を初期化します。後ろのパスは、後でこのリポジトリを上げる場所を書いておけば大丈夫です。今すぐ正確でなくても動作には支障ありません。

モジュール初期化 
hugo mod init github.com/自分のアカウント/my-docs

Hextra テーマの接続 #

設定ファイル hugo.yaml を開き、Hextra をモジュールとして読み込むように書きます。

hugo.yaml 
# hugo.yaml
baseURL: "https://example.com/"
title: 製品マニュアル
languageCode: ja

module:
  imports:
    - path: github.com/imfing/hextra

続いてテーマモジュールをダウンロードします。

テーマのダウンロード 
hugo mod get github.com/imfing/hextra

テーマを Git サブモジュールとしてコピーして入れる昔の方式と違い、モジュール方式はバージョンをコマンド一行で上げ下げできるので管理がすっきりします。

最初のドキュメントを表示する #

ではドキュメントを一枚作ります。まずは最初の画面になる content/_index.md です。

content/_index.md 
---
title: 製品マニュアル
---

私たちのチームの公式ドキュメントです。左のサイドバーから項目を選んでご覧ください。

続いて実際のドキュメントを一編追加します。

ドキュメント作成 
hugo new content docs/getting-started.md

作成されたファイルを開いて本文を埋めます。

content/docs/getting-started.md 
---
title: はじめに
---

## インストール

次のコマンドでインストールします。

```bash
npm install our-product
```

最後にローカルサーバーを起動します。ドラフト状態のドキュメントまで一緒に見るには -D オプションを付けます。

ローカルサーバー実行 
hugo server -D

ブラウザで http://localhost:1313 を開くと、Hextra の基本レイアウトに、たった今作ったドキュメントがサイドバーと共に現れます。ファイルを修正して保存すると、画面が自動でリロードされます。

フォルダ構造を理解する #

ここまでに作られた構造の中で、今すぐ知っておくべきは content 一か所です。

フォルダ構造 
my-docs/
├─ hugo.yaml        # サイト設定
├─ content/         # ドキュメント本文 (ここだけ埋めれば大丈夫です)
│  ├─ _index.md     # 最初の画面
│  └─ docs/
│     └─ getting-started.md
├─ static/          # 画像などそのまま提供するファイル
└─ go.mod           # モジュール一覧 (Hextra 依存の記録)

ドキュメントを増やす作業は、結局 content の下にマークダウンファイルを足すことです。フォルダ構造がそのままサイドバーの階層になります。この点がブログツールと最も違うところで、次回で本格的に扱う内容です。

まとめ #

この記事では、Hugo Extended と Go をインストールし、新しいサイトに Hextra を接続してローカルで最初のドキュメントを表示するところまで終えました。まだ基本的な骨格だけですが、マークダウンファイル一つがそのまま検索可能なドキュメントページになるという流れは確認できました。

次回では サイドバーの構成と検索 を扱います。ドキュメントが数十編に増えても読者が道に迷わないよう、情報構造を設計する段階です。

X