Hugo を Ananke テーマで使って Markdown から静的ページを作る

静的サイト構築をやってみます。

「Bootstrap + GitHub Pages でサイトを作る」
https://qiita.com/nanbuwks/items/6269418f905884cf467e

では Bootstrap を使いました。これはうまくいきましたが、markdown からページを生成する仕組みに進みたく、その場合に手作業が多すぎてどうかなあという感じでした。

そのようなことを踏まえて、別のフレームワークを考えています。 まずは Jykill で調べてみましたが、GitHub Pages で行うときの制限がどうもわかりずらくて、Strategy を立案する以前のところでくじけてしまいました。

# Hugo

ふと Hugo を見ると簡単そうだったのでやってみました。

作戦：

- GitHub でホスト、GitHub の CD/CI でコンパイル
- ローカルのCD/CIでコンパイル、GitHub Pages でotJibでホスト
- Netlyでホスト、コンパイルは?

今回は、ローカルのCD/CIでコンパイル、GitHub Pages で表示するやりかたを前提とします。

# 環境

- Ubuntu24.04


# Quickstart を元に

まずは https://gohugo.io/getting-started/quick-start/   を見て進めていきます。

# Hugo インストール

Ubuntu のディストリビューションパッケージだとバージョンが以下のように古く、
```
$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2024-11-06T01:07:23Z VendorInfo=ubuntu:0.123.7-1ubuntu0.2
```

以下からビルド済みバイナリをダウンロードしました。
https://github.com/gohugoio/hugo/releases/tag/v0.146.5

ダウンロードしたのは `hugo_extended_0.146.5_linux-amd64.deb` です。


```
$ sudo dpkg -i hugo_extended_0.146.5_linux-amd64.deb 
```

# サイト作成
```
$ hugo new site oshwc-hugo
Congratulations! Your new Hugo site was created in /home/owner/Downloads/oshwc-hugo.

Just a few more steps...

1. Change the current directory to /home/owner/Downloads/oshwc-hugo.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

```

```
$ cd oshwc-hugo
```

先に `5. Start the embedded web server with the command "hugo server --buildDrafts".`をやってみました。



```
$ hugo server --buildDrafts
Watching for changes in /home/owner/Downloads/oshwc-hugo/{archetypes,assets,content,data,i18n,layouts,static}
Watching for config changes in /home/owner/Downloads/oshwc-hugo/hugo.toml
Start building sites … 
hugo v0.146.5-61328976e11cbb9d906b4a790b8a7cd25b2a914f+extended linux/amd64 BuildDate=2025-04-15T17:54:38Z VendorInfo=gohugoio

WARN  found no layout file for "html" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

                   | EN  
-------------------+-----
  Pages            |  4  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  0  
  Processed images |  0  
  Aliases          |  0  
  Cleaned          |  0  

Built in 4 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) 
Press Ctrl+C to stop



```
http://localhost:1313  にアクセスすると

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/53ee30bb-3c6a-45e4-88ac-c091f01fd46f.png)

Webサーバー自体は動いているようです。

# テーマをインストール

`2. Create or install a theme:`

を行っていきます。

Quickstart では Ananke をテーマとして使っています。ほかのテーマも多々ありますが、こちらのサイトを見ると Ananke が良さそうなのでそのまま使うことにします。
https://girigiribauer.com/tech/20200128/

Anankeの公式サイトはこちら。
https://github.com/theNewDynamic/gohugo-theme-ananke

Ananke 公式のインストール方法を確認すると

> Installation
> Dive into our documentation on installing the theme as GoHugo Module or Git Submodule. The official setup guide of GoHugo covers the installation of the theme as Git Submodule.

ということなので、Quickstart で示しているやり方の通り以下のようにしました。

```
$ git init
$ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```

`3. Edit hugo.toml, setting the "theme" property to the theme name.`
を行っています。

```
$ echo "theme = 'ananke'" >> hugo.toml
```

改めて
```
$ hugo server --buildDrafts
```
とすると以下のようになりました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/cdbcf61c-8d28-4297-aa71-7dee1da1233c.png)

# コンテンツを追加する


```
$ hugo new content content/posts/1st-test-post.md
```

```
$ vim content/posts/1st-test-post.md 
```
中身は以下のようになっていました
```
+++
date = '2025-04-16T22:55:10+09:00'
draft = true
title = '1st Test Post'
+++
```
これを以下のように直すと
```
+++
date = '2025-04-16T22:55:10+09:00'
draft = true
title = '1st Test Post'
+++
## Test Post

Hello!
```
Webブラウザ上で自動で反映されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/de346136-aaad-4ed3-8bc6-3893e2fef02f.png)





# ページタイトルを変更する


hugo.toml の内容が以下のようになっていました。


```
baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'Mymy New Hugo Site'
theme = 'ananke'
```
これを以下のように変更。



```
baseURL = 'https://example.org/'
languageCode = 'ja'
title = 'OSHWC:OpenHardWareConference'
theme = 'ananke'
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/9e8d7e43-63fa-415b-b328-e35d40d340a9.png)

ついでに記事 Aboutusを追加しています。

# メニューを追加する

hugo.tomlに以下の内容を追加します。
```
[[menu.main]]
  identifier = "whatisOSHWC"
  name = "OSHWCとは"
  url = "/posts/whatisOSHWC/"
  weight = 10
[[menu.main]]
  identifier = "emtry"
  name = "出展・登壇申込"
  url = "/posts/entry/"
  weight = 20
[[menu.main]]
  identifier = "aboutus"
  name = "Aboutus"
  url = "/posts/aboutus/"
  weight = 30

  
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/8a516aee-a1e3-4b06-a876-446d5e02a2a6.png)

対応する記事を適当に増やしておきます。


# 記事の書き方

## 画像を貼る

スタンダードな markdown で以下のようにしても、0x0pixelとなり表示できなかった。Ananke の設定かな?

```
![]("/images/OSHWClogo20140105-400px.png")
```

Hugo オリジナルのショートコードだと表示できました。
```
{{< figure src="/images/OSHWClogo20140105-400px.png">}}
```

# デモサイトを参考にする
Ananke のデモはこれかな。
https://ananke-theme.netlify.app/
そのソース。
https://github.com/theNewDynamic/gohugo-theme-ananke/tree/master/exampleSite

それを基にして `content/_index.md` を以下のように作成してみる。

```
---
title: "OSHWC:オープンハードカンファレンス"

description: "2025年5月、埼玉県入間市にて再始動!"
# 1. To ensure Netlify triggers a build on our exampleSite instance, we need to change a file in the exampleSite directory.
theme_version: '2.8.2'
cascade:
  featured_image: '/images/IMG_20180909_125455.jpg'
---
ものづくりをオープンに交流、活用、楽しもう!

発表、展示、自慢をしてみよう!
```
 `static/images/` に `/images/IMG_20180909_125455.jpg` を置くと以下のようになる。
 
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/9f388291-fd5a-43a6-ba0f-eb078c7d2e52.png)

```
cascade:
  featured_image: '/images/IMG_20180909_125455.jpg'
```
を指定しているとすべてのページがヘッダーが大きく表示されるようになってしまったので `cascade:` フィールドを消して `featured_image: ` のみにしました。


# GitHub に登録

GitHub にレポジトリを作り、push します。

cf.,https://qiita.com/nanbuwks/items/4f6a685f0bb4953e75c8
「GitHub でよくあるトラブル対応の備忘録」→「ローカルで作ったソースコードを github に登録する」


# GitHub Pages に対応しようとしたけれども・・・

GitHub Page はユーザ名 nanbuwks , レポジトリ名 oshwc_hugo とすると、

https://nanbuwks.github.io

と 

https://nanbuwks.github.io/oshwc_hugo

の2つの公開方法がある。今回はレポジトリ名を含んだ下の方。


それに対応するために、hugo.toml ファイルに以下を追加

```
canonifyURLs  = true
```

更に、baseURL を変更します。

```
baseURL = 'https://nanbuwks.github.io/oshwc_hugo/'
```


一応これで github pages のレポジトリ名付きURLに対応したのですが、プレビュー時にテーマがうまく適用できなくなってしまいました。また、github pages で表示しても image ファイルのURLがうまいう設定できていませんでした。これは Ananke の問題なのかな?

以下によると

https://gohugo.io/content-management/urls/
- canonifyURLs 
- relativeURLs

は警告マーク付になっていて、あまり良い解決方法ではない感じです。

また、静的ページをレポジトリのいずこに置くかは以下の選択肢があります。

- ブランチのルートをドキュメントルートディレクトリとして公開
- ブランチのdocsディレクトリをドキュメントルートとして公開
- GitHub Actionで任意のディレクトリをGitHubPageで公開

今回は、「ブランチのdocsディレクトリをドキュメントルートとして公開」とします。
それに対応するために、hugo.tomlファイルに以下を追加

```
publishDir = "docs"
```

この状態で静的ページを生成する

```
$ hugo
```

これで docs ディレクトリに静的ページが生成される。

その上で GitHub 上のレポジトリに変更を反映。


「Bootstrap + GitHub Pages でサイトを作る」
https://qiita.com/nanbuwks/items/6269418f905884cf467e
の「GitHub Pages を使ってみる」を参照し同様に設定、

build元のフォルダ設定の箇所のみ、`/docs` に変更しておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/24924636-f8ba-4632-b271-3ad7a1683e2e.png)


一応、上記のように設定してみましたが今回の条件では色々問題があり実用にはなりそうにありません。

hugo.toml を元に戻して別の方法をもちいることにしました。

# Netify 対応

静的サイトをホスティングするサービスとして、 Netify が便利らしいです。
git サービスとの連携が簡単、Hugo サポート、無料で利用することもできるということで、 github に登録したコンテンツを github pages ではなくこちらで公開してみます。


https://www.netlify.com/ に Sign up

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/cde8a96b-773e-411b-865c-584970a258d3.png)

Sign Up した後、 Add your site で Import from Git を選びます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/184422fd-8398-4e07-bf60-41c9f38a3bc5.png)

GitHub 上のレポジトリを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/27ac67bd-94e2-4856-9c25-3ccbf1f2d548.png)

site name を希望のものに変更します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/c5aedea9-9194-44c2-9d7e-0235df7c078b.png)

command や publish directory は自動で設定されていました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/facdc5ff-058d-484c-a0d2-da8f4421d4db.png)

Environment variables を1つだけ追加する必要があります。最新のHUGOのバージョンをここに入れておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/fb33cff9-eda3-443b-a45d-41d4c6590e17.png)


下記はEnvirinment variables を入力し忘れた時。デプロイ時にエラーが出ています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/9eaeeefd-de7f-42a7-94fb-463887105c04.png)

無事デプロイすると以下のように公開されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/44de16ec-91dd-49fa-a875-3dd6e4f2ecb6.png)

# ドメインネームを Netlify ページに適用する

すでに oshwc.org ドメインを「お名前.com」で取得しています。そのドメインでアクセスできるようにします。
いくつかやりかたはありますが、 Netlify の DNS を使うやり方を試してみました。


「Domains」-Add or register domain の Add a domain you already own を選びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/7d370ea0-1af1-4e30-8784-369b8b6bc8e3.png)
oshwc.org を入れて「Verify」-「Add domain」
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/2deec142-d347-4abb-a35a-2ed554c13b65.png)

DNS settings の Name Servers に Netlify の DNS が 表示されています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/6a66b865-cfe3-4e4f-8f4c-66475e7e124a.png)

お名前.com のネームサーバ設定で、上記の DNS を入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/e97eaf86-efcd-404e-b330-8be79501cccf.png)


しばらくすると使えるようになります。ブラウザのキャッシュの問題があったため、プライベートブラウジングしたら表示されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/139524/070204c8-3922-4801-b056-37cec4cd677b.png)

ドメインを追加した直後は証明書が適用されていませんが、しばらくすると自動プロビジョニングでLet'sEncryptの証明書が追加され、 https:// でアクセスできるようになります。

# 静的ファイルを配置する

pdf をダウンロードさせたいのだけれど、どうすればいいかな?

`public/images` 中にファイルを置くと、

```
pdf はこちら https://oshwc.org/images/OSHWCproposal20250423.pdf

```

としてアクセスできた。

# css 

assets/ananke/css/ フォルダを作り、 custom.css ファイルを以下のように書きます。

table {
  border-collapse: collapse;
}
td, th {
  border: 1px solid #312;
  padding: 0 .2em;
}


hugo.toml 内に以下のように書きます。
[params]
custom_css = ["custom.css"]

hugo 
コマンドを入力すると、反映します。


assets/
# トラブルシューティング

## found no layout file for "HTML" for kind.

レポジトリをクローンしたもののページを更新しようとしたら、以下のような表示が出て反映しないことがある。

```
hugo: found no layout file for "HTML" for kind.
```


以下で解決
```
$ git submodule update --init
```

## Error: Unable to locate config file or config directory. Perhaps you need to create a new site.

ページを作ろうとしたら、以下のようにエラー。
```
$ hugo new content content/posts/oshwc2025saitamaparty.md
Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
       Run `hugo help new` for details.
```

はてなーと思ったら、遥かな過去にインストールしたままのバージョンの旧い hugo だった。

```
$ hugo version
hugo v0.92.2+extended linux/amd64 BuildDate=2023-01-31T11:11:57Z VendorInfo=ubuntu:0.92.2-1ubuntu0.1
```
アンインストールして
```
$ sudo apt remove hugo
```
レポジトリから最新版をインストール
```
$ sudo dpkg -i hugo_0.147.4_linux-amd64.deb 
```
うまくいきました。
```
$ hugo new content content/posts/oshwc2025saitamaparty.md
Content "/home/nanbuwks/Downloads/oshwc_hugo/content/posts/oshwc2025saitamaparty.md" created
```

# Error: failed to resolve "~~~" to an archetype template

```
$ hugo new content content/posts/oshwc2025saitama4exhivitors

Error: failed to resolve "content/posts/oshwc2025saitama4exhivitors" to an archetype template
```

.md をつけ忘れてました。


```
$ hugo new content content/posts/oshwc2025saitama4exhivitors.md
Content "/home/nanbuwks/Downloads/oshwc_hugo/content/posts/oshwc2025saitama4exhivitors.md" created
```