- Published on
Hugoでブログ作成
はてなブログからHugoを使って GitHub Pages に移行したときのメモです
Hugoは golang 製の静的サイトジェネレータで、カスタマイズが柔軟にできて、ビルドも速い
Table of Contents
背景
はてぶでブログを書いていたが、以下のような点で書きづらさを感じていた
- 好きなエディタを使って Markdown で記事を書きたい
- 履歴の管理をしたい
- オフライン環境でもプレビューしたい
調べてみると、静的サイトジェネレータ（static site generator）を使えば解決できそう。 これは、Markdown などで記事を書いて HTML へビルドするもので、GitHub Pages などで公開する。
有名所では、Jeklly、Hexo、Sphinx などがあるが、中でも Hugo というものが使いやすそうなので使ってみた。
Go 製でビルドが速い点が Hugo の売りらしい。自分の環境では、数記事で 1 回のビルドは数十ミリ秒。 以前使ったことのある Sphinx とくらべても速い印象。記事が増えてきてもこの速さは維持できるのかな。
Hugo のインストールと Tutorial
macOS で確認。
公式の Tutorial を参照したが、基本的には以下の手順
macOSにHugoをインストール
brew install hugo
./tkato-blogにhugoのプロジェクトを作成
hugo new tkato-blog cd ./tkato-blog
テーマなどの設定
vim config.toml
記事を作成
hugo init posts/20170813_hugo.md
プロジェクトのビルド
hugo
以上で、./tkato-blog/public/index.htmlで閲覧できる
Markdown で記事が書ける
hugo server -Dでリアルタイムにビルドしながらドキュメントを確認できる
hugo newで作成した記事は、あとからファイル名を変えても問題ないようだ。
Hugo の設定
ブログを書く上で、修正が必要なファイルや知っていると便利な機能を記載する。
config.toml
設定を記載。後述するテーマから参照する情報もある
尚、この設定ファイルは TOML 形式だけでなく、JSON や YAML でも書ける
archetypes
archetypes/default.md
記事を新規作成した時のテンプレートとなる
- GitHub の issue template みたいに、必要な章立てなどを記載するとよさそう
Shortcode
Markdown で書く記事内で使える関数のようなもの。 予め HTML でテンプレートを書いておき、Hugo のビルド時に展開される仕組み。
はてなブログで言うところの XX ですね。
例えば、記事中に{{< tweet 886120562761752576 >}}と書くと生成された HTML は以下のようになる。
https://twitter.com/_tkato_/status/886120562761752576
Shortcode には以下のようなメリットがある
- Markdown の記述が簡潔になる
- リッチなことをする場合でも、Markdown に HTML を直接埋め込まなくてよくなる
- メンテナンスが楽になる
- Shortcode 側の修正だけで、それを使う全ての記事が修正できる
- 例えば「画像埋め込み時のキャプション位置を修正したい」ときなど
デフォルトでいくつかの Shortcode がビルドインされていて、すぐ使うことができる
todo
- URL を貼るとはてぶ風の表示(linkcard という？)をする Shortcode {{< url >}}を作りたい
テーマ
テーマは自作もできるが、公開テーマがたくさんある。 例えば、OSS のプロジェクトの公式サイト風や、API ドキュメント風など様々なテーマがある
テーマにはタグが登録されているので、今回はblogタグで検索し、mainroadを使わせてもらうことにした。
Git のサブモジュールとしてプロジェクトに登録する
themesディレクトリの各設定よりもユーザー環境のほうが優先されるようで、以下のようにして CSS を上書きできた
$ mkdir static/css
$ cp themes/static/css/style.css static/css/
$ vim static/css/style.css # 好みのデザインに上書き
いずれは、以下のような機能を含む自分でテーマを作ってみたい
- Twitter や Pocket のリンクをフッターに表示するようにテンプレート化
- 作成日時と更新日時、ファイルの GitHub 履歴へのリンクを追加
- Hugo の公式ドキュメントのフッターを参考
- Qitia 風のスクロールする toc
- コメントの投稿機能をフッターに追加
ブログを書く上での運用など
記事の新規作成、更新について、以下のようにやっていこうと考えている。
- 記事の新規作成
hugo new posts/xxxx- 記事の Permalink は、Markdown のファイル名にする
- 後述
- 画像など、記事に関するファイルの保存場所
- static/img などに適当な名前で保存している
- ファイルが増えて整理が大変になった、命名規則など考えよう
- 記事の投稿
- 後述の GitHub Pages の機能を利用。GitHub へ push することで記事が公開される
- CI で Twitter へのポスト
masterブランチへのコミットは記事の更新として、Tweet- 特定のコミットメッセージを含む場合は、Tweet しないようにする
- 記事の追記
- 修正して、GitHub へ push
- 更新日時や、記事の修正履歴へのリンクは更新時に自動で埋め込まれるようにテンプレートに記載するようにする
記事の URL（Permalink）
投稿後に記事のタイトルや Markdown の保存ディレクトリは変えるかもしれないため、それに依存して URL が変わらないようにする
デフォルトでは、contentディレクトリ以下の Markdown へのパスとなる。 例えば、content/posts/2017/08/writing-blog-with-hugo-1.mdの URL はhttps://xxx/posts/2017/08/writing-blog-with-hugo-1/となる
Markdown のファイル名はそうそう変えないと思ったので、ファイル名を Permalink にするように設定。 例えば、上記の場合はhttps://xxx/posts/writing-blog-with-hugo-1/となるようにしたい。
Permalink を変えるには、config.toml に設定を書く。
設定方法の詳細はHugo | URL Management参照
以下のようにする。
[permalinks]
posts = "/:filename" # content/posts以下のパーマリンク
GitHub Pages へのデプロイ
Hugo の公式ドキュメントでは以下のページで解説がある
https://gohugo.io/hosting-and-deployment/hosting-on-github/
いくつかやり方があるが、Markdown で書いたソースとビルドされた HTML を同じリポジトリで管理したかったので、私は以下の方法とした
簡単な手順は、以下。
- リポジトリ作成
- https://github.com/tkat0/blog
- ブログの URL は https://tkat0.github.io/blog となる
- https://github.com/tkat0/blog
- config.toml に
publishDir = "docs"を記載 hugo実行で、docs ディレクトリが作成され、HTML が生成される- git commit && git push
ブログのコーディング環境
ATOM
現在は、ATOM でこの記事を書いている。
特に記事を書く上で役立っているプラグインは以下のもの。
- markdown-preview-enhanced
- Markdown を ATOM でリアルタイムプレビュー
- このプラグインでは Hugo のプロジェクトの画像が表示できないので、今はブラウザでのプレビューをメインで使っている
- document-outline
- Markdown のアウトラインの可視化
- platformio-ide-terminal
- ターミナル
hugo server -Dを実行しておき、ブラウザでリアルタイムプレビューできるようにする
- vim-mode-plus
- ATOM で Vim キーバインドを使う
Chrome
- Copy as Markdown - Chrome ウェブストア
- Web サイトのリンクを Markdown 形式にしてクリップボードにコピーしてくれる
はてなブログからの移行
- いまいま良い案はなさそう。記事も少ないので手動で頑張るか。
はてなブログは記事をエクスポートできるが、以下の制限がある
- MT（MovableType）形式
- 画像のエクスポートはできない