ブログジェネレータをTinkererからPelicanに移行した

Posted on: 2014-08-10

Tags: #tinkerer, #pelican, #githubpage

2014/09/06 一部タイポと文言を修正しました

これまでしばらくSphinxベースのTinkererを使ってReST -> HTML 変換を行いGithubpageにホスティングする形でやっておりましたが、Tinkererの部分をPelicanに移行しました。

移行の際にやったことをメモしておきます。

ちなみに、以下のものはすでに使えることを前提にします。

pyenv, pyenv-virtualenv
git
githubpage

Pelicanのインストール

python2.7系最新をインストール(3系の対応が完璧でないっぽいため)

# 最新版を確認
% pyenv install -l | grep 2.7

% pyenv install 2.7.8
% pyenv virtualenv 2.7.8 pelican

作業ディレクトリを適当に作成

% mkdir -p ~/work/blog
% cd ~/work/blog
% pyenv local pelican

Pelicanをインストール

## Pelican 本体をインストール
% pip install pelican

## Markdown も使いたいのでインストール
% pip install markdown

## plugin, themeもクローン
% git clone https://github.com/getpelican/pelican-plugins.git
% git clone https://github.com/getpelican/pelican-themes.git

これで ~/work/blog 配下で pelican コマンドが使えるようになります。

pelicanコマンドが使えるようになったら QuickStart しておきましょう。

% pelican-quickstart 
Welcome to pelican-quickstart v3.4.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

> Where do you want to create your new web site? [.] 
> What will be the title of this web site? 続・ラフなラボ
> Who will be the author of this web site? Kei Iwasaki
> What will be the default language of this web site? [en] ja
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) n
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) N
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at ~/work/blog

するとだいたい以下のような感じでファイルが生成されると思います。

~/work/blog
       ├── content
       ├── develop_server.sh
       ├── fabfile.py
       ├── Makefile
       ├── output
       ├── pelicanconf.py
       └── publishconf.py

TinkererからReSTファイルを移行

PelicanはReST、Markdownともにサポートしてますし、TinkererはSphinxベースのツールで元々ReSTはサポートしています。ただ、微妙に方言に違いがあってTinkererで使ってた*.rstファイルをそのままPelicanでビルドしようとすると落っこちます。また、デフォルト設定だとTinkerer管理のような content/YYYY/MM/DD/<slug>.rst の形式も日付や生成されるファイルのパス情報として読み込んでくれないかったり、画像ファイルを各日付ごとのディレクトリにおいても特に面倒は見てくれません。そのへん自力でなんとかする必要があります。(軽く調べた感じ、特に移行ツールなどは見つかりませんでした...)

ReSTファイルのコンバート, 画像ファイルの移動

一部ファイル書き換え程度ならシェル芸でさくっと行けたかもしれないですが、ファイルの内容を違う行に移動させるのが流石にしんどかったので、今回はやっつけなpythonスクリプトを書きかました。※pyenv-virtualenv 環境に合わせるため2.7系で書いてます。

laughk/tinker2pelican-rst

基本的にこちらのREADME.md に従っていけば、とりあえずコンテンツの移行はできると思います。

Githubpage向けのファイルを移行

Githubpage を利用してホスティングする際に必要な静的ファイルも移行します。 output ディレクトリ配下を git 管理することになるので私の場合はHTMLを生成する際に一緒に生成されるようにしています。

そのため以下のような感じでファイルを置き、pelicanconf.py の設定をしています。

ファイル

~/work/blog/content/extra
                      |---- empty           (空ファイル, Githubpage用 .nojekyllとして利用する。)
                      |---- gitignore       (output用のgitignore)
                      |---- CNAME           (Githubpage用の CNAMEファイル)
                      `---- gooleXXXXXXXX   (GoogleAnalytics用のの静的HTMLファイル。テンプレート扱いされないように拡張子はなし)

pelicanconf.py

EXTRA_PATH_METADATA = {
    'images':           {'path': 'images'     },
    'extra/CNAME':      {'path': 'CNAME'      },       # for original domain
    'extra/empty':      {'path': '.nojekyll'  },       # for Githubpage
    'extra/gitignore':  {'path': '.gitignore' },       # for Githubpage
    'extra/gooleXXXXXXXX':
        {'path': 'gooleXXXXXXXX' },                    # for google analytics
}

試しにブログを生成してブラウザから見てみる

ここまできたら、一度HTMLファイルを生成してローカルでプレビューしてみます。

% pelican content -S pelicanconf.py -o output

## pelican-quickstartの際に Makefile を生成していた場合は以下でもOK
% make html

% cd output && python -m SimpleHTTPServer

この状態で http://localhost:8000 にアクセスすれば、生成されたブログをブラウザから確認できます。

設定をいじって自分好みにカスタムしていく

データの移行ができたらあとは純粋にPelicanを自分用に作りこんでいきます。詳細なカスタマイズに関しては今回は割愛しますが、公式のドキュメントが充実していたり、テーマも充実しているので色々試してみるのがいいと思います。

公式ドキュメント Pelican 3.4.0 — Pelican 3.4.0 documentation
テーマ getpelican/pelican-themes

その他テーマをいじっていた時のメモ

この辺はざっくりと。

完全に気に入るようなものは Pelican の充実したテーマの中でも見つからないんで、結局カスタム。
pelican-bootstrap3 が一番カスタムしやすそうだったので、ベースに導入。
Addthis でソーシャルボタンが一発で行けるかと思いきやURLに勝手に #xx-xxxxxxx ってつけられてキモいので削除、自力でテンプレ作成。
広告入れる場合はレスポンシブデザインか小さいサイズにしておかないと思わぬところでデザインが崩れる。
画像もレスポンシブ対策をCSSにしないとデザインが崩れる。
pulishconf.py に RELATEVE_URLS = False 入れておかないとホスティングの際にDISCUSのコメント欄が死ぬ (相対パスになっちゃったSITEURLがDISCUS用のJSのパラメータに渡っちゃうため)
生成に必要な部分と生成物はこれまで違うレポジトリで管理していたけど、ghp-import なるものがあったので、生成物をgh-pagesブランチ、設定ファイルや元のMarkdown,ReSTファイルなどはmasterブランチという形でレポジトリを統合。

最後に

単純にTinkererからPelicanに移す場合はReSTの方言に気をつければそこまで手間がかかることではないかもしてませんが、テーマを作りこんだりPelicanそのものの使い勝手がよくわからずはまってしまったり、せっかくの機会だからブランチを意識して一人プルリクフローで作っていったり、各ブランチに違うレポジトリ追加して管理方法を変えてみたりとやっていたら想像以上に大掛かりな作業になってしまいました。。(まるまる4日間)

ただ、Pelicanはテーマも充実していますしMarkdownも使えたり、一部iframeを埋め込もうとするとビルドが落っこちるとかはないので非常によいですね。 MarkdownとReSTの混合状態でもいい感じでビルドしてくれます。MarkdownのGFM対応がちょっと中途半端な感じがあるのが残念ですが、概ね Tinkerer より個人的にしっくり来ています。