静的サイトジェネレータ Hexo で生成したブログを github pages で公開するまでの手順のメモ
はじめに 見出しへのリンク
.md や .py といったテキストファイルから、静的なドキュメントやブログ（つまり html/css/js）を生成するツールを 静的サイトジェネレータ (static site generator; SSG) と呼びます。SSG を使うと、例えば、markdown でブログを書くことが出来て、しかもそのソースコードをバージョン管理できます。
世の中にはたくさんの SSG があり、次のようなページで簡潔にまとめられています。
この記事では、Hexo と呼ばれる Javascript 製の SSG について注目します。 Hexo の一般的な使い方は次のようなサイト等にまとめられていますが、ここで自分の使いやすい環境を構築することに専念して、その手順を完結に示したいと思います。
インストール 見出しへのリンク
本体 見出しへのリンク
npm install hexo-cli -g
# cd working-dirctory
hexo init <blog-name>
設定 _config.yml の大まかな設定方法
title: タイトル
slug: hexo-blog
subtitle: サブタイトル
description: ブログの説明
keywords:
- キーワード1
- キーワード2
author: OpenJNY
language: ja
timezone: Asia/Tokyo
url: https://openjny.github.io/
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
new_post_name: :year-:month-:day-:title.md # File name of new posts
default_layout: post
titlecase: true # Transform title into titlecase
filename_case: 1 # lower-case
external_link: true # Open external links in new tab
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
レンダリング 見出しへのリンク
数式や GHF な md を書くために render エンジンを pandoc へ変更する。
npm uninstall hexo-renderer-marked
npm i hexo-renderer-pandoc --save
katex で数式をレンダリングするために hexo-katex-macros を導入する。
npm i hexo-katex-macros --save
そのままでも使えるが、マクロを設定したければ、ソースコードを管理してるリポジトリにサンプルがあるのでそれを参考にしながら _config.yml に記述。1
# _config.yml
katex:
macros:
"\\set": "\\left\\{ #1 \\right\\}"
デプロイ 見出しへのリンク
サイトの生成からデプロイまでを自動化する為に hexo-deployer-git を追加する。
使い方は hexo deploy g みたいな感じ。
npm i hexo-deployer-git --save
設定は _config.yml を次のようにする。
deploy:
type: git
repo: git@github.com:OpenJNY/openjny.github.io.git
branch: master
message: "[update] Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"
なお、gh-pages 以外のホスティングサービスを使うときは、それに応じて適当なものインストールするか、CI/CD 機能を使ってデプロイを行うと良い。
テーマ 見出しへのリンク
hexo-theme-next という名前の素晴らしいテーマがあるので、それをフォークしたものを使う。
自分用にカスタマイズした設定をフォーク先のレポジトリで管理することで、複数のブログを作るときに使いやすくする狙いがある。
ちなみにこれがそう。
こいつを themes に配置する。
git submodule add git@github.com:OpenJNY/hexo-theme-next.git themes/next
その他 見出しへのリンク
VS Code による執筆 見出しへのリンク
vs code には hexo の記事を書くときに色々嬉しいことがあります。 markdown の preview だとか textlint だとかは、割とどのエディタでも使えるものですが、特に vs code ならではの利点は Paste Image。
Paste Image は画像を扱う vs code のプラグインで、こいつはかなりの優れもの。 クリップボードにコピーされている画像を markdown に埋め込みつつ、いい感じに実体化してくれます。
例えば、.vscode/settings.json を次のように設定すれば、source/images/{article-name}/{datetime}.png として自動的に実体化し、そのパスを makrdown に埋め込んでくれる。
"pasteImage.defaultName": "Y-MM-DD-HH-mm-ss",
"pasteImage.insertPattern": "",
"pasteImage.path": "${projectRoot}/source/images/${currentFileNameWithoutExt}",
"pasteImage.basePath": "${projectRoot}/source",
"pasteImage.forceUnixStyleSeparator": true,
"pasteImage.prefix": "/"
普段でもかなり重宝しているので、hexo に関係なくインストールすることをオススメしたい。
Git によるソースコード管理 見出しへのリンク
この手順で作成したブログを GitHub で公開してます。
src ブランチでソースコードを管理し、master に生成した html たちを配置して公開する運用をとっています。
「その他」までで示した手順を踏んだ後、次のようなことをすれば、同じような結果になると思います。
git init
git commit -a -m ":tada: initial commit"
git remote add origin awesome-repository
git push -u origin master:src
hexo deploy
このような環境では、新たな記事が次のような流れで執筆できます。
# create a new post
hexo new post "Awesome article"
# edit it
code $(find source/_posts -maxdepth 1 -type f -print0 | xargs -0 ls -drt | tail -n 1)
# deploy and backup
git commit -am "perfect commit"
git push origin HEAD:src # or simply $ git push
hexo clean && hexo deploy
また、新しいPC等で再度環境を整えるには、次の手順を踏むだけでOKです。
git clone --recurse-submodules -b src git@github.com:OpenJNY/openjny.github.io.git blog
cd blog
npm install
何かの参考になれば幸いです。