Nikolaでブログ構築してGithub Pagesに設置

Hiromasa OHASHI — Sun, 07 Jan 2018 14:35:28 GMT

Nikolaとは

Python製のstatic site generator。python製だとpelicanの方が有名だがipynbが使えると聞いたのでこちらを使うことにした。

Nikolaでブログを生成

インストール

pipでインストールできる。

$ pip install nikola
$ pip install webassets

後述するbuildの際などに下記のようなメッセージが出るので合わせてwebassetsもインストールしておくと良い。

[2018-01-08T01:42:01Z] WARNING: Nikola: In order to USE_BUNDLES, you must install the "webassets" Python package.
[2018-01-08T01:42:01Z] WARNING: bundles: Setting USE_BUNDLES to False.

ブログの雛形生成

nikolaはgitのようにnikola サブコマンドの形式で様々なコマンドを実行できる。雛形の生成のためにはnikola initを実行する。

nikola init blog_name

これを実行するとCUIベースで対話的に様々な設定が可能。 commentシステムとして何を使うかを聞かれるが、後でconf.pyを書き換えれば設定が可能な模様であるため一旦は空白で良い。

なおGetting Startedではinitの際に引数に--demoを付けているが、この引数を付けるとデモ用コンテンツが生成されてしまうので普通に真っさらな状態で始めたいならば付けない方が良い。

新記事生成

新記事生成は下記の通り。

$ nikola new_post -f markdown  # formatを-fで指定(デフォルトはReStructuredText形式)

実行すると記事タイトルを聞かれるので打ち込むと-fで指定した形式のファイルがposts以下に生成される。また、引数に-eを付けるとそのままエディタでの編集画面となる。

生成されたファイルの冒頭には下記のような形のヘッダーが付いている。

<!--
.. title: Nikolaでブログ構築してGithub Pagesに設置
.. slug: 1
.. date: 2018-01-07 23:35:28 UTC+09:00
.. tags: nikola, python, github
.. category: 
.. link: 
.. description: 
.. type: text
-->

titleは記事タイトルである。 slugはurlの一部となる文字列である。記事タイトルをアルファベットに直したものが記載されているが、適当に修正すると良い。1にしておくとhttp://www.hiromasa.info/1/のようなURLとなる。

固定ページ生成

固定ページはpostではなくpageとして生成する。

$ nikola new_page -f markdown pages/about

生成した固定ページを上部ナビゲーションに配置する方法は下記のようにconf.pyのNAVIGATION_LINKSに書けば良い。

NAVIGATION_LINKS = {
    DEFAULT_LANG: (
        ("/archive.html", "文書一覧"),
        ("/categories/", "タグ"),
        ("/pages/about/index.html", "About"),
        ("/rss.xml", "RSSフィード"),
    ),
}

ブログ構築

postやpageを上記のように生成しただけでは単なるテキストが生成されているだけなので、これらを元にブログを構築する。

$ nikola build

これでブログが構築される。ローカルで確認するためには下記を実行する。

$ nikola serve -b  # --browserでも良い

ブログテーマ設定

デフォルトはbootstrap3になるようであるが、他のものに変えたい場合はthemesのページから好きなものを選ぶ。ここではlibrettoのテーマを選んだ。 wordpressの同名テーマをベースにしたものらしい。

テーマのインストールは下記の通り。

$ nikola theme -i libretto

実行するとthemesディレクトリ以下にlibrettoのテーマがダウンロードされる。

このテーマを使用するためには更にconf.pyを編集する必要がある。

# Name of the theme to use.
# THEME = "bootstrap3"
THEME = "libretto"

この上でnikola buildを実行すれば更新後のテーマに変わっている。記事の一文字目だけ大きく表示されるのが若干気に入らないがとりあえずこれで行く。

※2017/1/8追記、librettoだとsyntax highlightが効かないようなのでbootstrap4のテーマに変えた

Github Pagesに配置

HandbookのDeploymentの項を見るとGithubでホスティングする方法が記載されている。ここではGitHubのuser page(wrist.github.io)に配置することを考える。

1. gitリポジトリの設定を行う

過去にwrist.github.ioリポジトリを作成しているため、ブログのルートでgit initしてからremoteを設定する。

$ git init
$ git remote add origin git@github.com:wrist/wrist.github.io

2. (必要であれば)conf.pyを編集する

必要であれば下記を編集する。今回は不要であるため特に変更していない。

# siteのソースがdeployされるブランチ名、srcが推奨とのこと
GITHUB_SOURCE_BRANCH = 'src'
# HTMLファイルがdeployされるブランチ、user pageの場合はmaster
GITHUB_DEPLOY_BRANCH = 'master'
# gitのremote名
GITHUB_REMOTE_NAME = 'origin'
# ソースブランチを自動的にコミットしプッシュするかの設定
GITHUB_COMMIT_SOURCE = True

3. .gitignoreを追加

下記内容を.gitignoreに追加する。

cache
.doit.db
__pycache__
output

4. deploy用のコマンドを実行

下記コマンドを実行することでdeployが可能。

$ nikola github_deploy

下記のように表示された場合はpip install ghp-import2でghp-import2をインストールする。

[2018-01-08T04:16:04Z] ERROR: Nikola: In order to deploy the site to GitHub Pages, you must install the "ghp-import2" Python package.
[2018-01-08T04:16:04Z] ERROR: Nikola: Exiting due to missing dependencies.

通常はこれで改めてnikola github_deployを実行すれば終わりのはずである。しかし、今回は過去に作成済の既にmasterが存在しているリポジトリにpushしようとしているため、当然先にfetchしろと警告が出て失敗する。

[2018-01-08T04:17:10Z] INFO: github_deploy: ==> ['ghp-import', '-n', '-m', 'Nikola auto commit.\n\nSource commit: a37690e35a31dc4a108f53c62b8ee17e783aa28f\nNikola version: 7.8.11', '-p', '-r', 'origin', '-b', 'master', 'output']
To github.com:wrist/wrist.github.io
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'git@github.com:wrist/wrist.github.io'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

仕方ないのでこの記事に倣い、先にmasterを強制pushする。

$ git push -f origin master
$ nikola github_deploy

これにて無事にhttp://wrist.github.ioで閲覧できるようになった。

5. 独自ドメインでの使用

github pagesを独自ドメインで使用する場合にはCNAMEファイルをリポジトリのルートに配置しておく必要があるが、このためにnikolaではソースブランチのfilesの下にCNAMEファイルを配置しておけば、これをbuild時にoutputディレクトリにコピーしてくれる。

コメントシステムの設置

init時には空白にしておいたコメントシステムを有効化する。ここではdisqusを用いることにする。conf.pyに下記を追記する。

COMMENT_SYSTEM = "disqus"
COMMENT_SYSTEM_ID = "hiromasa-info"

COMMENT_SYSTEM_IDはdisqusの場合はshortnameを設定する。 shortnameはdisqusのsiteのsettingsから確認できる。

その他

記事のデフォルト形式をmarkdownに変えたいが方法が分からないためHandbookを読んでもう少し調べる必要があるが、 ReStructuredTextで書くとExtensionとしていくつかのdirectiveやroleが使えるようでもあるため、もう少し使ってみてから考えたい。

hiromasa.info (Posts about github)