はじめに
書けと言われたので記憶とzshの履歴を頼りに頑張って書きました．
去年あたりからAsciidocにハマり， 趣味のことはAsciidocで書きたい[1] というのがこの構成の動機です (そもそもブログに書くようなことを最近何もやってないのですが…)．
今回はローカル環境でHugoによる静的サイト生成までをまとめました． GitHub Pages で生成したブログを公開する方法は (力尽きたので) 次で書きます．
前提
以下の環境を想定しています．
-
Ubuntu 18.04 LTS (x64)
-
Hugo (v0.64.0)
Asciidocってなに?
Markdownのようなマークアップ言語の一つです．
「数式を多用する論文・レポートはLaTexのほうが楽だと思うけど，そこまで書かないならAsciidocのほうがオススメ」という Markdown 以上 LaTex 以下? な言語というのが使っている人間の感想です．
Markdown と比較して方言 (処理系による記述の差異) が少ないこと，豊富な表現がデフォルトで存在することや， レポート形式やBook形式などのテンプレートがある点が良い点だと思っています．
html への変換や PDF への変換がRubyで実装されています．
Hugoってなに?
静的サイトジェネレータの一つです． MarkdownやAsciidocで記述したコンテンツをブログのようなWebサイト形式に変換してくれます．
Asciidocの書き方
文法は この辺りのサイト を参考させていただいて，適時やりたいことをググればいいと思います． Asciidocで書いた文書のプレビューを見たい場合は以下の方法がお手軽です．
- VSCodeの場合
-
asciidoctor-vscodeをインストールする
- その他のテキストエディタの場合
-
Google Chromeの拡張機能 をインストールする
htmlを生成したい場合はasciidoctorをインストールします(次節)．
Asciidoctorのインストール
後述のHugoでAsciidocを使用するためにHugoの実行環境にAsciidoctorをインストールする必要があります．
AsciidoctorはRubyに依存しているため，
Rubyのパッケージマネージャーである gem 経由でインストールします (aptで直接インストールもできるようです)．
$ gem install -U asciidoctor # うまく行かない場合は -U オプションを外して sudo をつける
# または
$ sudo apt install asciidoctorHugo の使い方
インストール
Ubuntuユーザーは apt install hugo でインストールできます．
特定のバージョンを入れたい場合は Hugoのreleaseページ からバイナリをダウンロードしてパスを通すなりします．
私は バイナリを落として来て /usr/local/bin に配置しました．
hugo version をshellで実行し，以下のようなバージョン情報が出力されれば問題ないです．
$ hugo version
Hugo Static Site Generator v0.64.0-241DB8F7 linux/amd64 BuildDate: 2020-02-04T09:10:23Z雛形の生成
最初に以下のコマンドでサイトの雛形を生成します．
hugo new site <生成場所><生成場所> に指定したディレクトリ下に以下のファイル/ディレクトリが生成されます．
sample という名前のディレクトリを指定した場合のツリー構造sample ├── archetypes │ └── default.md ├── config.toml ├── content ├── data ├── layouts ├── static └── themes
生成されたファイル/ディレクトリはそれぞれ以下のような役割になってます．
- archetypes
-
後述のページ生成コマンドを実行した時に使用されるテンプレートファイルを置きます． デフォルトでは Markdown しかないため，Asciidoc用のテンプレートファイルを自分で配置します．
- config.toml
-
生成するサイトのタイトルやURL, テーマ等の設定を記述します．
- content
-
ページを構成するファイル置き場． 自分で書いたAsciidocなどのファイルやページ内で表示する画像ファイル等を置きます．
- theme
-
サイトのテーマ用データを配置するディレクトリです． ココ でお好きなテーマを探してこのディレクトリ下に置きます． git管理する場合は
git submoduleでレポジトリに追加する流れが定石っぽいです． 私は beatutifulhugo を使用しています． - data, layouts, static
-
ナニニツカウカワカリマセン．
これらのファイルの他に，サイト生成コマンドの実行結果であるhtml等を格納した public ディレクトリがここに追加されます．
記事の追加
テンプレートの作成
Markdown用のテンプレートは最初から含まれていますが，
Asciidocで記事を書くために以下のようなテンプレートファイル
を archetypes 下に作成します．
---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
isCJKLanguage: true
---
= タイトル
== セクション--- で囲われた領域はHugo特有の記述で，各ページのプロパティを指定する箇所です．
記事の新規作成
hugo new コマンドで記事を作成します．
$ hugo new <作成するファイルパス>上記コマンドを実行することで，content ディレクトリ下にファイルが生成されます．
content/<作成するファイルパス>
例として以下のように指定します．
$ hugo new posts/sample.adoc
beautifulhugoは content/posts/ 以下のファイルを読み込むようなので，ファイル名の前に posts/ を指定しています．
上記コマンドを実行することで，先程作成したテンプレートファイルをもとに以下のファイルが生成されます．
---
title: "Sample"
date: 2020-07-23T17:06:42+09:00
draft: true
aliases:
categories:
tags:
comments: false
description: ""
keywords:
isCJKLanguage: true
---
= タイトル
== セクション記事本文の前に，ページのプロパティを記述します． 最低限設定が必要なのは以下のプロパティです．
- title
-
指定した文字列が記事のタイトルに反映されます．HugoではAsciidocのタイトルヘッダー(
= or #) は無視されます． - draft
-
これが
trueになっていると ページ生成の対象外となります．公開する際にfalseに変更します． - isCJKLanguage
-
設定しておかないと日本語を含む場合にレイアウト等が崩れるかも?
後はAsciidocの書式で書いていきます．
サイト全体の設定
config.tomlにはサイト全体の設定を記述します． 最低限必要そうな記述は以下の項目です．
# サイトトップに表示されるタイトル
title = "Sample"
# 使用するテーマ．themesディレクトリに同名のディレクトリがないとエラーになる
theme = "beautifulhugo"
# 日本語を含む場合に設定しておくもの?
defaultContentLanguage = "ja"
languageCode = "ja"
hasCJKLanguage= trueサイトの生成
記事を書いたら，サイトのhtmlを生成します．
プロジェクトのトップディレクトリ
(content ディレクトリがある階層) で以下のコマンドを実行します．
$ hugo
エラーがなければ， public ディレクトリが生成され，その内にサイトを構成するhtmlがあります．
ただ，執筆途中にプレビューを確認する場合は，ローカルでサーバーを立ち上げてくれる hugo server コマンドが楽です．
ファイルの状態を監視して変更がある度，自動でhtmlを再生成してくれます．
$ hugo server -D #実行シェルを専有するため，別ペインで実行するのがオススメ
-D オプションは draft: true のファイルも生成の対象とするためのオプションです．
-D, --buildDrafts include content marked as draft
コマンドを実行するとサーバーが立ち上がります．
... Web Server is available at //localhost:1313/ (bind address 127.0.0.1) ...
ログに表示されているアドレスに
適当なブラウザで ( localhost:1313 ) アクセスするとサイトのトップページが表示されます．
おわりに
次は，ここで生成したhtmlをGitHub Pagesで公開する方法について書きます．(この4連休中に書きたい)