helpdelete

静的サイトジェネレータHugoをさわろう

静的サイトジェネレータ とは？

静的サイトジェネレータとは、Markdownテキスト※1などの「コンテンツ」とデザイン、レイアウト情報などを含む「テンプレート」を合わせてHTMLファイル、CSSファイル、javascriptファイルなどから成る「静的サイト」を生成するツールです。 「コンテンツ」と「テンプレート」は完全に分離した状態でローカルマシンで管理します。

static-site-generator.png

静的サイトジェネレータの種類により、おおまかにテンプレートとジェネレータの実装が異なります。このあと比較してみたいと思います。

※1 Markdownは軽量マークアップ言語。HTML生成用に開発され、現在はいろいろな用途で使用されています。可読性を保持したまま手早く「文書構成」を記すのに向いています。

静的サイトジェネレータの種類

ssg-logos.png

ジェネレータの実装言語、テンプレートのフレームワーク、特徴などを一覧にしました。

種類実装言語Template FW特徴
Hugo GoGo機能はシンプル。HTML生成がとにかく高速
Jekyll RubyLiquid 2017年一番人気。機能やテーマが充実している。
Gatsby JavaScriptReact PWA (Progressive Web App)を生成できる。
Next.js JavaScriptReactServer Side Rendering(SSR)が初期実装されている。
Nuxt.js JavaScriptVue Vue.jsアプリケーションを静的に生成できる。
Expose  (demo )BashHTML写真、動画のギャラリーサイトを生成できる。
GitBook  (demo )JavaScriptJinja2 ドキュメントサイトを生成できる。

JavaScript系のジェネレータで作った静的サイトは静的と言いながらぬるぬる動きます。説明がむずかしいです。「JAMstack 」の勉強会をだれかお願いします！

JAMstackをざっくり。

  • クライアント(ブラウザ)からのリクエストとレスポンスはすべてJavaScriptで制御します。js系のフレームワークまたはライブラリ、または素のJavaScript(vanilla JavaScript)で実現。
  • サーバでの処理、データアクセスはすべて再利用可能なAPIにしてJavaScriptを使ってHTTP通信で別系のサービスまたは外部のサービスと連携します。
  • 静的サイトジェネレータかWEBアプリ用のビルドツールで生成済みのMarkup(HTML)をデプロイします。

Go言語製の静的サイトジェネレータHugo

めっちゃ速いってInductorさんとかMorixさんが言ってました。 golangに興味があるので今回これをさわっていきます。

Hugoをさわってみよう。

Hugoのセットアップ

作業環境

Hugoのインストール

Hugoの公式ドキュメントで2つの方法が紹介されていました。

  1. Hugoのバイナリを設置する 
  2. パッケージマネージャでインストールする 

Hugo本体はたった1つのバイナリ(hugo.exe)なので、それを任意のフォルダに設置するだけで、インストール完了です。

ただ、動作環境に合ったものを探しに行ったりするのが面倒だし、せっかくなので2.のパッケージマネージャを使っていこうと思います！

パッケージマネージャChocolatey を使用します。 chocolatey-icon.png

Chocolateyのインストール

PowerShellを管理者権限で起動します。

powershelladmin.png

PowerShellの下記コマンド※1でChocolateyインストールのシェルスクリプトを実行します。

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

※1 インターネット上のシェルスクリプトを実行するために、一時的に実行ポリシーを変更しています。「Bypass」はインターネットからダウンロードされた署名されていないスクリプトなども何もブロックされず、警告もメッセージも表示しないポリシー「-Scope Process」でプロセスにのみ適用「-Force」で警告を含む全てのプロンプト表示を抑制

インストール確認

chocoコマンドでバージョンが表示されていたらインストールできています。

PS C:\WINDOWS\system32> choco
Chocolatey v0.10.11
Please run 'choco -?' or 'choco <command> -?' for help menu.
Hugoのインストール(choco install)

choco installコマンドでHugoをインストールします。

choco install hugo --confirm

※2 「--confirm」オプションは「-y」と書き換えてもOKです。全ての確認に「はい」と応答するオプションです。

こんな感じで進んでいきます。

Chocolatey v0.10.11
Installing the following packages:
hugo
By installing you accept licenses for the packages.
Progress: Downloading hugo 0.47.1... 100%

hugo v0.47.1 [Approved]
hugo package files install completed. Performing other installation steps.
The package hugo wants to run 'chocolateyInstall.ps1'.
Note: If you don't run this script, the installation will fail.
Note: To confirm automatically next time, use '-y' or consider:
choco feature enable -n allowGlobalConfirmation
Do you want to run the script?([Y]es/[N]o/[P]rint):Y

Hugoの 最新版のダウンロードとインストールがはじまります。

Downloading hugo 64 bit
  from 'https://github.com/spf13/hugo/releases/download/v0.47.1/hugo_0.47.1_Windows-64bit.zip'
Progress: 100% - Completed download of C:\WINDOWS\system32\onfig\hugo\0.47.1\hugo_0.47.1_Windows-64bit.zip (17.96 MB).
Download of hugo_0.47.1_Windows-64bit.zip (17.96 MB) completed.
Hashes match.
Extracting C:\WINDOWS\system32\onfig\hugo\0.47.1\hugo_0.47.1_Windows-64bit.zip to C:\ProgramData\chocolatey\lib\hugo\tools...
C:\ProgramData\chocolatey\lib\hugo\tools
 The install of hugo was successful.
  Software installed to 'C:\ProgramData\chocolatey\lib\hugo\tools'

Chocolatey installed 1/1 packages.
 See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

Software installed to 'C:\ProgramData\chocolatey\lib\hugo\tools'

と、Hugoがインストールされた場所が表示されます。クリップボードなどに控えてください。

Hugoのpathを通します。

Hugoのpathを通して 、どこからでもhugoコマンドを実行できるようにします。

hugo-env-var.png

［コントロールパネル］→［システムとセキュリティ］→［システム］→［システムの詳細設定］→ ［環境変数］

「ユーザ環境変数」の 「Path」 をダブルクリック

新規作成で

C:\ProgramData\chocolatey\lib\hugo\toolsを登録してOKボタンをクリック

環境変数の追加が終わったら、念のためPowerShellを再起動します。

Hugoのpathが通ったことの確認

PS C:\Users\nacco> hugo version
Hugo Static Site Generator v0.47.1 windows/amd64 BuildDate: 2018-08-20T08:17:26Z

Hugoプロジェクトの作成、初期化

Hugoプロジェクトの作成

Hugoプロジェクトのディレクトリ(フォルダ)を作成します。

まずプロジェクトの格納元C:\Hugoディレクトリを作成します。

Hugoプロジェクトの初期化

PowerShell(もしくはコマンドプロンプト)でC:\Hugoに移動

hugo new siteコマンド実行します。

hugo new site [project]

C:\Hugo>hugo new site naccoblog 

Congratulations! Your new Hugo site is created in C:\Hugo\naccoblog.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

ディレクトリの説明

  • archetypes … 新規コンテンツ作成時の原型default.mdを置く場所
  • assets … Hugo Pipes という新機能で利用する場所
  • content … コンテンツ(.mdファイル)を置く場所
  • data … Webサイト生成の設定ファイル(YAML、JSON、TOML)を置く場所
  • layouts … テンプレート(ただしテーマを設定するとthemes\theme-nameディレクトリ下のlayoutsを参照)
  • static … 静的コンテンツ(画像、CSS、JavaScriptなど)を置く場所。WEBサイト生成時にそのままコピーされる
  • config.toml … Hugo本体の設定ファイル

テーマの設定

Hugoのテーマは https://themes.gohugo.io/  から選べます！

今回「Minimo 」を使います！

テーマのダウンロード

テーマのダウンロード方法は以下の2種類(gitを使うことが多いです)

  1. テーマのGitHubリポジトリをgit cloneまたはダウンロードする(Hugoプロジェクト内themesに単純にコピー)
  2. テーマのGitHubリポジトリをgit submoduleにする

submodule化するとテーマのみを更新したりできますが、そういうことはしない予定なので今回は1.の手順。

テーマのリポジトリをgit cloneまたはダウンロードします。

C:\Hugo\naccoblog>git clone --depth 1 https://github.com/MunifTanjim/minimo themes/minimo

git cloneしてきた場合は、themes/theme-nameディレクトリ内の.gitディレクトリは削除しましょう。(外部リポジトリの設定が混入すると想定しない動作をするため。) del-git-dir.png

テーマの適用

config.toml(Hugoの設定ファイル)にテーマを追加します。

baseURL = "http://example.org/"
languageCode = "ja"
title = "My New Hugo Site"
# add theme 
theme = "minimo"

theme = "minimo"でテーマの適用ができます。

config.tomlの設定はこれだけでは足りません

テーマのGitHubリポジトリの exampleSite/config.toml  にサンプルが置いてあるので、コピーして設定値を追記してください。だいたいexampleSite下にサンプルが置いてあります。

コンテンツの作成

Hello World! 的なサンプルコンテンツ(記事)を書きます。

コンテンツ(Markdownファイル)を新規作成します。hugo newコマンドを実行します。

hugo new [path]

C:\Hugo\naccoblog>hugo new posts/my-first-post.md

Markdownファイルを編集してみます。.mdファイルはここに作成されます。

C:\Hugo\naccoblog\content\posts\my-first-post.md

---
date: "2018-09-26T02:44:13+09:00"
title: "My First Post | My New Hugo Site"
draft: true
---

Hello World!
テスト投稿です。

---で囲まれた部分はコンテンツのメタ情報、それ以下が本文になります。

まずは本文に何か適当に文章を入れてください。メタ情報については今回はそのままで大丈夫です。

メタ情報(Front Matter )はyaml形式、toml形式、json形式で書くことができます。今回はyaml。

  • yaml形式は---で囲みます
  • toml形式は+++で囲みます
  • json形式は{``}で囲みます

メタ情報の項目

  • date … 投稿日時
  • title … 記事タイトル
  • draft … 下書きフラグ

ローカルでHugoサーバを起動、プレビュー

HugoはWEBサーバ(Hugoサーバ)を素早くローカルマシン上で起動することができます。

Hugoサーバはコンテンツの変更を検知して、メモリ上でサイトを生成して提供します。(生成データはディスクに保存しません) また、LiveReload.js を組込んであるので追加パッケージなしで、変更をリアルタイムに表示反映します。

どういうことかと言うと、Hugoサーバを起動した状態で、Markdownファイルを編集し、保存すると即座にブラウザに反映して表示してくれます。

Hugoサーバの起動

hugo serverコマンドでWEBサーバを起動します。

C:\Hugo\naccoblog>hugo server -D

※1 「-D」オプションはdraft(下書き)のコンテンツもプレビューします。メタ情報に「draft: true」と書いたら下書き(非公開)記事です。

Building sites …
                   | JA | EN
+------------------+----+----+
  Pages            | 39 | 12
  Paginator pages  |  0 |  0
  Non-page files   |  0 |  0
  Static files     | 35 | 35
  Processed images |  0 |  0
  Aliases          | 11 |  1
  Sitemaps         |  2 |  1
  Cleaned          |  0 |  0

Total in 115 ms
Watching for changes in C:\Hugo\naccoblog\{content,data,layouts,static,themes}
Watching for config changes in C:\Hugo\naccoblog\config.toml
Serving pages from memory
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
WEBブラウザで表示

ブラウザでhttp://localhost:1313/にアクセスすると、サイトをプレビューできます。

トップページhttp://localhost:1313/

minimo-preview1.png

記事のページhttp://localhost:1313/posts/my-first-post/

minimo-preview2.png

Markdownファイルの記事のタイトルを編集して、保存してみます。

設定ファイル(config.toml)のメニュー名を編集して、保存してみます。