Hugo でプロダクトのドキュメントサイトを構築する

業務でプロダクトのドキュメントを Hugo で作成したので、メモを残しておきます。

Hugo とは
使用したテーマ（Hextra）
構築
おわりに

Hugo とは

Hugoは、Go 言語で書かれた高速かつ柔軟な静的サイトジェネレーターです。静的サイトジェネレーターは、事前にコンテンツを生成し、HTMLファイルとして配信します。このため、非常に高速で、セキュリティ面でも優れています。また、Markdown 形式でコンテンツを簡単に作成でき、多様なテーマが用意されているため、デザインも自由にカスタマイズできます。

使用したテーマ（Hextra）

今回は、Hugo Theme 一覧からドキュメントに向いてそうと思った「Hextra」を採用しました。
シンプルなデザイン、Mermaid をサポートしている、全文検索をサポートしている、ダークモードへの切り替えが簡単、なあたりがいいなと思いました。
ちなみに Hextraのドキュメントも Hugo/Hextra で作られています。

構築

セットアップ

Hugo インストール

brew でインストール可能です。

brew install hugo

プロジェクト作成

# プロジェクトのディレクトリを作成
hugo new site my-site --format=yaml

# hugo モジュール作成
cd my-site
hugo mod init {モジュールパス}

# Hextra テーマを追加
hugo mod get github.com/imfing/hextra

hugo.yaml に以下を追記します。（一番上の階層です。）

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

コンテンツ追加

以下のコマンドで Markdown ファイルが作成されます。

hugo new content/_index.md
hugo new content/docs/_index.md

ローカルにサイトを構築する。

hugo server --buildDrafts --disableFastRender

http://localhost:1313/にサイトが立ちます。

Hugo の config 設定

hugo.yaml で、細かな設定が可能です。
今回は以下のようになりました。

baseURL: https://example.org/
title: タイトル

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

defaultContentLanguage: ja
languages:
  ja:
    languageName: 日本語
    weight: 1

menu:
  main: # メインメニューの設定
    - name: Search # 全文検索用の検索窓
      weight: 1
      params:
        type: search
    - name: GitLab # このサイトの GitLab リポジトリのリンクアイコン
      weight: 2
      url: "{リポジトリリンク}"
      params:
        icon: gitlab
  sidebar: # サイドバーのコンテンツ以外の設定
    - identifier: more
      name: More
      params:
        type: separator
      weight: 1
    - identifier: hugoDocs
      name: "Hugo ドキュメント"
      url: "https://gohugo.io/documentation/"
      weight: 2
    - identifier: hextraDocs
      name: "Hextra ドキュメント"
      url: "https://imfing.github.io/hextra/"
      weight: 3

params:
  navbar: # ナビゲーションバーの設定
    displayTitle: true # タイトルを表示する
    displayLogo: true # ロゴを表示する
    logo: # カスタマイズするには、./static/images/logo.png のように画像ファイルを配置
      path: images/logo.png # static の下から記載
      dark: images/logo.png # static の下から記載
      link: / # タイトルをクリックしたときにルートに遷移する
      width: 40
      height: 40
    width: full # full (100%), wide (90rem), normal (1280px)

  page:
    width: full # full (100%), wide (90rem), normal (1280px)

  theme:
    default: system # light | dark | system
    displayToggle: true

  footer: # フッターの設定
    enable: false # 表示しない

  editURL: # ページごとの編集リンクの設定
    enable: true # リンクを表示する
    base: "{gitlab リポジトリパス}/-/edit/main/content" # ベース編集リンク

  highlight: # コードボックスの設定
    copy: # コピーボタン
      enable: true
      # hover | always
      display: hover

  enableInlineShortcodes: true # ショートコードを有効化する

  search: # 全文検索の設定
    enable: true
    type: flexsearch

    flexsearch:
      index: content # インデックスする対象: content | summary | heading | title
      tokenize: full # インデックスの粒度: full | forward | reverse | strict

コンテンツを充実させる

ドキュメントタイプのレイアウトにする

Hextra のレイアウトには、docs, blog, default の3タイプありますが、今回は docs を使います。 docs タイプはディレクトリ構成に合わせた構造化されたドキュメントを表現できます。

content/_index.md の先頭を以下のように変更します。

---
title: 'ホームページ'
cascade:
  type: docs
---

階層化されたことを確認するため、ページを追加してみます。

hugo new content/docs/page01/_index.md
hugo new content/docs/page02/_index.md

./content/docs/page01/_index.md

---
title: 'ページ01'
weight: 1
---

./content/docs/page02/_index.md

---
title: 'ページ02'
weight: 2
---

以下のようになりました。
サイドバーに階層が表現され、ページの上部にパンくずも表示されました。

ショートコードによるコンテンツ埋め込み

コールアウト

注意書きやノートを簡単に配置できます。

{{< callout type="warning" >}}
  このページは 3年以上更新されていません。情報が古くなっている可能性があります。
{{< /callout >}}

カード

カードを配置できます。アイコンや画像を設定したり、リンクにすることも可能です。

Youtube

Youtube の動画埋め込みも対応されており、プレイヤーの設定も簡単です。
以下は、自動再生、ループ再生、プレイヤーのコントローラー非表示としています。

{{< youtube id=xxxxxxxxx autoplay=true controls=false loop=true >}}

固定された文言を変更する

ページ編集画面へのリンクの文言が、「このページをGitHubで編集→」となっています。
今回は GitLab を使用しているので変えられないかなーと思って調べたところ、Hetraのi18n/ja.yamlで設定された値が使われていました。

./i18n/ja.yaml を自作して上書きすることで変更できます。

backToTop: "トップにスクロール"
changeLanguage: "言語を変更"
changeTheme: "テーマを変更"
copyright: "© 2024 Hextra プロジェクト。"
dark: "ダーク"
editThisPage: "このページをGitLabで編集 →"
lastUpdated: "最終更新日"
light: "ライト"
noResultsFound: "結果が見つかりませんでした。"
onThisPage: "このページの内容"
poweredBy: "提供元 Hextra"
readMore: "もっと読む →"
searchPlaceholder: "検索..."

変更できました。

GitLab Pages へのデプロイ

Hetraドキュメントの Deploy Siteに GitHub Pages、Cloudflare Pages、Netlify、Vercel へのデプロイ方法が記載されています。
今回は、社内の Gitlab Pages にデプロイしたかったので、それ用の .gitlab-ci.yml を用意しました。

.gitlab-ci.yml

image: hugomods/hugo:ci-0.131.0

variables:
  HUGO_ENV: production

cache:
  paths:
    - .hugo_cache

pages:
  script:
    - hugo mod get -u
    - hugo
  artifacts:
    paths:
      - public
  only:
    - main

変更が main ブランチに反映されてから 10秒程度で、GitLab Pages が更新されていました。

おわりに

Hugo/Hextra を使ってプロダクトドキュメントを構築しました。
シンプルですが、無駄なくいい感じのデザインのサイトを簡単に作れました。