Hugo v0.16 theme の利用
目的
theme を利用して Hugo によるサイトを構築する。
Theme
今回は material-docsを利用する。 技術的なドキュメントをまとめるサイトに適していそうだったので選択した。 これを利用して Hugo のフレームワークの理解を深める。
出来上がり
こんな感じになります。
Top page
Projects page
Hugo directory structure
Themes ディレクトリを省くと６ファイル程度しか修正していない。
. ├── archetypes/ ├── content/ │ ├── About/ │ │ └── index.md │ ├── environments/ │ │ └── env-a.md │ ├── projects/ │ │ ├── project-a.md │ │ └── project-b.md │ └── index.md ├── data/ ├── layouts/ ├── public/ ├── static/ └── config.toml
theme の導入
themes ディレクトリの中で以下のコマンドを実行する。
$ git clone https://github.com/digitalcraftsman/hugo-material-docs.git
新規に追加
content 以下の 5 ファイルは新規に追加している。
projects and environments
projects, environments ディレクトリは個々に好きな名前にして問題ありません。 あくまでも私の場合を示しているだけです。
$ hugo new projects/project-a.md
を実行すると content/projects/project-a.md が作成できる。 これはhttp://localhost:1313/projects/project-a/ でアクセスできる場所にファイルが生成される。 内容は物凄く適当です。
+++ date = "2016-09-04T16:42:07+09:00" title = "project a" +++ ## Purpose To be a big man. ## HOGE To be a big hoge.
Top page
このファイルは特別なので、hugo new コマンドを使わなくてもよく、 私は直接以下の内容で content/index.md を作成した。
+++ title = "Sample" type = "index" copyright = "katogiso" +++
Front matter で type を index にしているのには意味があります。 これで theme の適用を制御しています。
既存ファイルの修正
theme の修正
複数形を単数形にする自動機能のせいでサイトタイトルの "Tech-nia" がおかしくなったので、とりあえずこの機能を削除した。 ただし、Front matter でそれを制御するように修正したほうが良いと今更思う。
--- a/layouts/partials/header.html +++ b/layouts/partials/header.html @@ -7,7 +7,7 @@ </div> <div class="stretch"> <div class="title"> - {{ .Title | singularize }} + {{ .Title }} </div> </div>
全体だとこんな感じファイルは themes/hugo-material-docs/layouts/partials/header.html
<nav aria-label="Header"> <div class="bar default"> <div class="button button-menu" role="button" aria-label="Menu"> <label class="toggle-button icon icon-menu" for="toggle-drawer"> <span></span> </label> </div> <div class="stretch"> <div class="title"> {{ .Title }} </div> </div> {{ with .Site.Social.twitter }} <div class="button button-twitter" role="button" aria-label="Twitter"> <a href="https://twitter.com/{{ . }}" title="@{{ . }} on Twitter" target="_blank" class="toggle-button icon icon-twitter"></a> </div> {{ end }} {{ with .Site.Social.github }} <div class="button button-github" role="button" aria-label="GitHub"> <a href="https://github.com/{{ . }}" title="@{{ . }} on GitHub" target="_blank" class="toggle-button icon icon-github"></a> </div> {{ end }} <!-- TODO: disabled until Hugo supports the generation of a content index natively <div class="button button-search" role="button" aria-label="Search"> <label class="toggle-button icon icon-search" title="Search" for="toggle-search"></label> </div> --> </div> <div class="bar search"> <div class="button button-close" role="button" aria-label="Close"> <label class="toggle-button icon icon-back" for="toggle-search"></label> </div> <div class="stretch"> <div class="field"> <input class="query" type="text" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck> </div> </div> <div class="button button-reset" role="button" aria-label="Search"> <button class="toggle-button icon icon-close" id="reset-search"></button> </div> </div> </nav>
config.toml の修正
以下のように修正、追記している。
baseurl = "http://replace-this-with-your-hugo-site.com/" languageCode = "en-us" title = "Tech-nia" theme = "hugo-material-docs" [params] author = "So KATOGI" description = "Sample data for understanding the hugo" [params.palette] primary = "indigo" accent = "orange" [[menu.main]] name = "Projects list" url = "/projects/" weight = "0" [[menu.main]] name = "Environments list" url = "/environments/" weight = "10" [[menu.main]] name = "About" url = "/about/" weight = "20"
theme の選択
以下の記述でテーマを選択する。 コマンドラインオプションで指定もできるが、決めてしまえば設定しておくほうが圧倒的に楽だ。
theme = "hugo-material-docs"
menu の作成
自分で追加したファイルの content 直下のディレクトリを指定する。
[[menu.main]] name = "Projects list" url = "/projects/" weight = "0" [[menu.main]] name = "Environments list" url = "/environments/" weight = "10" [[menu.main]] name = "About" url = "/about/" weight = "20"
細かいカスタマイズ
色を params.palette で変更して、サイドメニューに表示されるauthor の付随パラメータを修正する。
[params] author = "So KATOGI" description = "Sample data for understanding the hugo" [params.palette] primary = "indigo" accent = "orange"
hugo サーバ
hugo には内蔵サーバがあり、ファイルの修正をリアルタイムで反映する機能がある。 これを起動しておくと、表示を確認しながら作業ができる。
$ hugo -v server
INFO: 2016/09/05 00:09:01 hugo.go:463: Using config file: config.toml
INFO: 2016/09/05 00:09:01 hugo.go:575: using a UnionFS for static directory comprised of:
INFO: 2016/09/05 00:09:01 hugo.go:576: Base: themes/hugo-material-docs/static
INFO: 2016/09/05 00:09:01 hugo.go:577: Overlay: static/
INFO: 2016/09/05 00:09:01 hugo.go:609: syncing static files to /
Started building site
INFO: 2016/09/05 00:09:01 site.go:1251: found taxonomies: map[string]string{"tag":"tags", "category":"categories"}
WARN: 2016/09/05 00:09:01 site.go:1990: "404.html" is rendered empty
0 draft content
0 future content
5 pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
in 33 ms
Watching for changes in theme/{data,content,layouts,static,themes}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
メッセージ通り http://localhost:1313/ にブラウザでアクセスすれば良い。 もちろん index.md を作成しないとただのブランクページしか見えないです。
Pretty URL
- content/projects/project-a.md
で作成したファイルは
- public/projects/project-a/index.html
へ生成される。 通常 Web サーバーは http://example.com/hoge/ のようにファイルを指定するようなアクセスではないとき、 index.html をURLに付加した http://example.com/hoge/index.html を表示しようとする。
このファイル名を省略した URL でアクセスすることを前提としたデータをHugoはデフォルトで生成し、 その URL を Pretty URL と呼んでいる。 これは他の Generator でも使われる用語です。
hugo でのファイル生成
hugo コマンドをトップディレクトリで実行するだけで良い。
$ hugo Started building site 0 draft content 0 future content 5 pages created 0 non-page files copied 0 paginator pages created 0 tags created 0 categories created in 43 ms
そうすると public 以下に必要なファイルが生成される。 theme の css などもコピーされる。
