hugoで静的なサイトを構築する（②Docker版で作る基本構成編） #ドキュメント

はじめに

hugoのチュートリアルに沿って静的サイトを作っていきます。
前回の記事はこちら。

有志によるDocker版

今回はklakegg氏のDockerイメージを使います。
公式のソースをビルドしてDockerイメージを作る方が軽量になるようですが、最適化は後で考えることにします。

実行環境

OS: macOS
Docker Engine: 20.10.20

とりあえず実行しよう

現在のディレクトリをコンテナにマウントするため、適当な作業フォルダに移動してからチュートリアルのコマンドを実行。

% docker run --rm -it -v $(pwd):/src klakegg/hugo:0.101.0

Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
       Run `hugo help new` for details.

Total in 43 ms

hugo help newを実行してくれとのこと。

% docker run --rm -it -v $(pwd):/src klakegg/hugo:0.101.0 help new
Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.

You can also specify the kind with `-k KIND`.

If archetypes are provided in your theme or site, they will be used.

Ensure you run this within the root directory of your site.

Usage:
  hugo new [path] [flags]
  hugo new [command]

Available Commands:
  site        Create a new site (skeleton)
  theme       Create a new theme

(中略)

Use "hugo new [command] --help" for more information about a command.

真っ白な状況から作りたいので、スケルトンを作るhugo new siteする。

% docker run --rm -it -v $(pwd):/src klakegg/hugo:0.101.0 new site --help
Create a new site in the provided directory.
The new site will have the correct structure, but no content or theme yet.
Use `hugo new [contentPath]` to create new content.

Usage:
  hugo new site [path] [flags]

(略)

まだソースとなるコンテンツがないと言われている。後続のコマンドでhugoのソースを格納するディレクトリを作ろう。

hugo用のディレクトリを構成する

hugo new site {任意のフォルダ名}を実行する。フォルダ名はdocumentsとする。

% docker run --rm -it -v $(pwd):/src klakegg/hugo:0.101.0 new site documents
Congratulations! Your new Hugo site is created in /src/documents.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

{カレントディレクトリ}/{指定したフォルダ名}/配下にhugoのディレクトリが構成された。まずはヨシ。

コマンドラインにこの後やることが示されている。

https://themes.gohugo.io/ より、テーマをダウンロードして{コンテキストパス}/themes 配置する。または、テーマ作成用のコマンドを実行する。
ページを足したいときに使うコマンド。
サーバー起動のコマンド。コンテンツを用意したらこれを使ってサーバーを起動する。

テーマの選定

https://themes.gohugo.io/ より、テーマをダウンロードして{コンテキストパス}/themes 配置する。または、テーマ作成用のコマンドを実行する。

今回は公開されているテーマを利用する。

小規模なサイトやブログにそのまま使えそうだなぁ、と思いながらドキュメント用のテーマを探す。一応、サイドメニューからタグで絞り込める。

RELEAN

まず目に入ったのがRELEAN。テキストが読みやすく、サイドバーが良い感じ。
しかし画面描画の時にレイアウトの調整などをしているためか、微妙に画面がガタつくのが気になった。
それがなかったら採用していたかも。惜しい。

docuapi

他にはdocuapiが気に入ったが、今回はテキスト中心の設計書（用語集）のテンプレートを目標にしているため選ばなかった。
docuapiはメイン画面に説明を書いて、右側にサンプルコードを示せる。
もしAPIの使い方やコード規約などのドキュメントを起こすならこれがいいな。

Geekdocs

最終的に選んだのはGeekdocs。
選定の理由はサイト構造の分かり易さと、テキストそのものの読みやすさ。
設計書のテンプレートなので。参照のし易さと本文で勝負させないといけませんしね。

テーマの導入

さて、Geekdocsのサイトのチュートリアルを進めます。
Geekdocsのテーマは事前にビルドされたものを使う。
Gitからクローンする手順も公開されているが、カスタマイズはパスしてビルド済のものを使う。

% cd {作業ディレウトリ}/documents
% mkdir -p themes/hugo-geekdoc/
% curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1

ダウンロードとtarの解凍が行われ、テーマの配置が完了。

Geekdocsの手順通りconfig.tomlを上書きする。
baseURLはURLになるためあらかじめ変えておく。

baseURL = "http://localhost/documents"
title = "documents"
theme = "hugo-geekdoc"

pluralizeListTitles = false

# Geekdoc required configuration
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true

# Required if you want to render robots.txt template
enableRobotsTXT = true

# Needed for mermaid shortcodes
[markup]
  [markup.goldmark.renderer]
    # Needed for mermaid shortcode
    unsafe = true
  [markup.tableOfContents]
    startLevel = 1
    endLevel = 9

[taxonomies]
   tag = "tags"

ページの作成

Hugoのチュートリアルの内容を振り返る。

2. Perhaps you want to add some content. You can add single files with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".

コンテンツを作成する。まずはトップページ。
md形式で編集させる想定のため、index.mdとした。

% docker run -it -v $(pwd):/src klakegg/hugo:0.101.0 new index.md

documents/index.mdが作成される。

---
title: ""
date: 2022-11-26T01:57:36Z
draft: true
---

テスト用の本文を追加。なお、draft: trueだとページが公開されないためfalseにする。

---
title: "タイトル"
date: 2022-11-26T01:57:36Z
draft: false
---

# level1

- item1
- item2
- item3

## level2

|column1|column2|
|----|----|
|data1-1|data1-2|
|data2-1|data2-2|

サーバー起動

index.mdを作ったところで起動する。

-v $(pwd):/src：ホストの現在のディレクトリとHugoコンテナのsrcをマウント
--name：コンテナ名
-p 1313:1313：ホストの1313ポート（左）とHugoコンテナの1313ポート（右）をマッピング

% docker run -v $(pwd):/src --name hugo -p 1313:1313 klakegg/hugo:0.101.0 server
Start building sites … 
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66 linux/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio

                   | EN   
-------------------+------
  Pages            |   8  
  Paginator pages  |   0  
  Non-page files   |   0  
  Static files     | 132  
  Processed images |   0  
  Aliases          |   1  
  Sitemaps         |   1  
  Cleaned          |   0  

Built in 1687 ms
Watching for changes in /src/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /src/config.toml
Environment: "DEV"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/documents/ (bind address 0.0.0.0)
Press Ctrl+C to stop

http://localhost:1313/documents/ にアクセスする。

良い感じですね。次回に続きます。