読者です 読者をやめる 読者になる 読者になる

Hugo v0.16 theme の利用

目的

theme を利用して Hugo によるサイトを構築する。

Theme

今回は material-docsを利用する。 技術的なドキュメントをまとめるサイトに適していそうだったので選択した。 これを利用して Hugo のフレームワークの理解を深める。

出来上がり

こんな感じになります。

Top page

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

Projects page

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

Hugo directory structure

Themes ディレクトリを省くと6ファイル程度しか修正していない。

.
├── 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 などもコピーされる。