Hugo v0.16 事始め

目的

データ処理した結果をHTMLでまとめたいが、テンプレートで処理したいときに使おうと考えている。 また、自分で見るだけの資料なら体裁は最低限で良いが、他者に見せるのであれば見栄えも重要だと思っている。

今回は Hugo の使い方を記事にしていきます。

Hugo

注意

この記事は基本的に Hugo quick start guide を再編集した程度の内容になります。

やること

今回は基本的なことを確認しておく。

  1. hugo new site で作成されるものを確認する。
  2. hugo new で何かしらの記事を作成する。
  3. layout などを作成する。
  4. 記事の生成をする.
  5. ブラウザで確認する。

最終構成

自分で作成するファイルは

  1. content/chartjs/base.md (記事にする内容を記載する)
  2. layouts/chartjs/single.thml (レイアウト情報を記載する)
.
├── archetypes/
├── content/
│   └── chartjs/
│       └── base.md
├── data/
├── layouts/
│   └── chartjs/
│       └── single.html
├── public/
│   ├── chartjs/
│   │   ├── base/
│   │   │   └── index.html
│   │   ├── index.html
│   │   └── index.xml
│   ├── 404.html
│   ├── index.html
│   ├── index.xml
│   └── sitemap.xml
├── static/
├── themes/
└── config.toml

content/chartjs/base.md

gist0f2c513a5b490e46bc84f939926ea41f

layouts/chartjs/sinble.thml

gist95ac4185d519019005613ad25fc3a9ad

hugo new site

とりあえず新規に作成する。

$ hugo new site base

以下のようなディレクトリとファイルが作成される.

.
├── archetypes/
├── content/
├── data/
├── layouts/
├── static/
├── themes/
└── config.toml

6 directories, 1 file

config.toml は

baseurl = "http://replace-this-with-your-hugo-site.com/"
languageCode = "en-us"
title = "My New Hugo Site"

こんな感じの内容で、まずはこのままにしておく事にする。

TOML

Tom's Obvious, Minimal Language の略で、仕様は以下でメンテナンスされているが、

TOML

今日現在で v0.4.0 であり、今後も仕様が変化する旨が宣言されている。 ざっと見た感じだと YAML よりは記述しやすそうだが、一方で、 こういった設定ファイルの記述方法は日々色々なモノが提案されて採用されていくので、Web エンジニア以外には多かれ少なかれ障害になっている気もする。

hugo new something_contens.md

$ hugo new chartjs/base.md

$ tree -F -I themes --dirsfirst

.
├── archetypes/
├── content/
│   └── chartjs/
│       └── base.md
├── data/
├── layouts/
├── static/
└── config.toml

hugo new でコンテンツを作ると、 content/ ディレクトリ以下に作成される。 ちょっと Markdown で記事を書いてみる。

記事の編集

+++
date = "2016-08-28T14:28:49+09:00"
draft = false 
title = "hugo new something_contens.md"

+++

# hugo new something_contens.md

<pre>
$ hugo new chartjs/base.md

$ tree -F -I themes --dirsfirst

.
├── archetypes/
├── content/
│   └── chartjs/
│       └── base.md
├── data/
├── layouts/
├── static/
└── config.toml
</pre>

hugo new でコンテンツを作ると、 content/ ディレクトリ以下に作成される。
ちょっと Markdown で記事を書いてみる。

"+++" で囲まれている箇所は、Front matter と呼ばれていてテンプレートで使用するパラメータを記載しておく箇所となる。 つまり、Front matter はその記事に特有の Parameter(その記事のタイトルとか)を Generator に渡すための記述です。 この用語、Front matter はその他の Web 系アプリでもよく出くわす単語です。

ちょっと静的 Generator に関しての概要

HTML で複数の記事を書くと同じようなことを複数のHTMLに書く必要が出てくる。 これをテンプレート化して、さらにフレームワーク化したものが静的 Generator です。

<html>
  <head>
    <title>This is template</title>
  </head>
  <body>
    <!-- Your content is here! -->
  </body>
</html>

この時、テンプレートの body 領域に markdown などで記載した記事を流しこめばとりあえず generator になる。 ただし、どうしても body 領域の外側、head領域などにある title などを上書きしないとならなくなる。

それを実現するために template 上は title の中身を変数にしておき、記事の Front matter の同名の変数で上書きする機能をGenerator に実装してあるのが一般的です。

書いた記事を生成(ビルド)する

hugo でとりあえずビルドしてみる。

$ hugo 
Started building site
=============================================================
Your rendered home page is blank: /index.html is zero-length
 * Did you specify a theme on the command-line or in your
   "config.toml" file?  (Current theme: "")
 * For more debugging information, run "hugo -v"
=============================================================
0 of 1 draft rendered
0 future content
0 pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
in 10 ms

サーバの起動前にコンテンツの生成が行われているが、 Front matter で draft が true になっているため、何もコンテンツが作成されていない。 ここで、"draft = false" にファイルを編集する。

+++
date = "2016-08-28T14:28:49+09:00"
draft = false
title = "hugo new something_contens.md"

+++

と編集してから、再度生成する。

$ hugo 
Started building site
=============================================================
Your rendered home page is blank: /index.html is zero-length
 * Did you specify a theme on the command-line or in your
   "config.toml" file?  (Current theme: "")
 * For more debugging information, run "hugo -v"
=============================================================
0 draft content
0 future content
1 pages created
0 non-page files copied
0 paginator pages created
0 categories created
0 tags created
in 7 ms

"1 pages created" となっている。

$ tree -F --dirsfirst
.
├── archetypes/
├── content/
│   └── chartjs/
│       └── base.md
├── data/
├── layouts/
├── public/
│   ├── chartjs/
│   │   ├── base/
│   │   │   └── index.html
│   │   ├── index.html
│   │   └── index.xml
│   ├── 404.html
│   ├── index.html
│   ├── index.xml
│   └── sitemap.xml
├── static/
├── themes/
└── config.toml

public の下に色々出来たが、お目当ての生成ファイルは public/chartjs/base/index.html です。 でもまだ、なにも中身がありません。 そこでメッセージ付き(-vオプション)で生成する。

$ hugo -v 
INFO: 2016/08/29 22:20:51 hugo.go:463: Using config file: /home/so/work/hugo/samples/base/config.toml
WARN: 2016/08/29 22:20:51 hugo.go:551: Unable to find Theme Static Directory: 
INFO: 2016/08/29 22:20:51 hugo.go:571: /home/so/work/hugo/samples/base/static/ is the only static directory available to sync from
INFO: 2016/08/29 22:20:51 hugo.go:609: syncing static files to /home/so/work/hugo/samples/base/public/
Started building site
INFO: 2016/08/29 22:20:51 site.go:1251: found taxonomies: map[string]string{"tag":"tags", "category":"categories"}
WARN: 2016/08/29 22:20:51 site.go:2014: Unable to locate layout for section chartjs: [section/chartjs.html _default/section.html _default/list.html indexes/chartjs.html _default/indexes.html]
WARN: 2016/08/29 22:20:51 site.go:1990: "chartjs" is rendered empty
WARN: 2016/08/29 22:20:51 site.go:2014: Unable to locate layout for page chartjs/base.md: [chartjs/single.html _default/single.html theme/chartjs/single.html theme/_default/single.html _default/single.html]
WARN: 2016/08/29 22:20:51 site.go:1990: "chartjs/base.html" is rendered empty
WARN: 2016/08/29 22:20:51 site.go:2014: Unable to locate layout for homepage: [index.html _default/list.html]
WARN: 2016/08/29 22:20:51 site.go:1990: "/" is rendered empty
=============================================================
Your rendered home page is blank: /index.html is zero-length
 * Did you specify a theme on the command-line or in your
   "config.toml" file?  (Current theme: "")
=============================================================
WARN: 2016/08/29 22:20:51 site.go:2014: Unable to locate layout for 404 page: [404.html]
WARN: 2016/08/29 22:20:51 site.go:1990: "404.html" is rendered empty
0 draft content
0 future content
1 pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
in 6 ms

メッセージをよく見ると、

WARN: 2016/08/29 22:20:51 site.go:2014: Unable to locate layout for page chartjs/base.md: [chartjs/single.html default/single.html theme/chartjs/single.html theme/default/single.html _default/single.html]

WARN: 2016/08/29 22:20:51 site.go:1990: "chartjs/base.html" is rendered empty

こんな感じで、layout が無いよと警告されています。 そしてなにも生成できなかったことを教えてくれています。

書いた記事のレイアウトファイルを作成する。

ここで layout ファイルを公式ドキュメントのBlock Templatesを参考に記述してみる。(詳細は別記する予定です。)

$ cat layouts/chartjs/single.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title> {{ .Title }} &ndash; {{ .Site.Title }}</title>
  </head>
  <body>
    <h1>This page is generated with layouts/chartjs/single.html</h1>
    {{ .Content }}
  </body>
</html>

"{{ .Content }}" に content/chartjs/base.md の内容が挿入される。 hugo コマンドで、で生成すると以下のように中身が記述されているのがわかる。

$ cat public/chartjs/base/index.html 
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title> hugo new something_contens.md &ndash; My New Hugo Site</title>
  </head>
  <body>
    <h1>This page is generated with layouts/chartjs/single.html</h1>
    

<h1 id="hugo-new-something-contens-md">hugo new something_contens.md</h1>

<pre><code class="language-shell">
$ hugo new chartjs/base.md

$ tree -F -I themes --dirsfirst

.
├── archetypes/
├── content/
│   └── chartjs/
│       └── base.md
├── data/
├── layouts/
├── static/
└── config.toml
</code></pre>

<p>hugo new でコンテンツを作ると、 content/ ディレクトリ以下に作成される。
ちょっと Markdown で記事を書いてみる。</p>

  </body>
</html>

書いた記事をWebブラウザで確認する。

hugo の Webサーバを使って確認する。

$ hugo server
Started building site
=============================================================
Your rendered home page is blank: /index.html is zero-length
 * Did you specify a theme on the command-line or in your
   "config.toml" file?  (Current theme: "")
 * For more debugging information, run "hugo -v"
=============================================================
0 draft content
0 future content
1 pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
in 11 ms
Watching for changes in /home/so/work/hugo/samples/base/{data,content,layouts,static}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

f:id:katogiso-tech:20160829231719p:plain