Hugo v0.16 事始め
目的
データ処理した結果をHTMLでまとめたいが、テンプレートで処理したいときに使おうと考えている。 また、自分で見るだけの資料なら体裁は最低限で良いが、他者に見せるのであれば見栄えも重要だと思っている。
今回は Hugo の使い方を記事にしていきます。
注意
この記事は基本的に Hugo quick start guide を再編集した程度の内容になります。
やること
今回は基本的なことを確認しておく。
- hugo new site で作成されるものを確認する。
- hugo new で何かしらの記事を作成する。
- layout などを作成する。
- 記事の生成をする.
- ブラウザで確認する。
最終構成
自分で作成するファイルは
- content/chartjs/base.md (記事にする内容を記載する)
- 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 の略で、仕様は以下でメンテナンスされているが、
今日現在で 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 }} – {{ .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 – 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