静的サイトジェネレータ Plican で AsciiDoc を機能させるのに必要な、文書化されていない作業をまとめました。AsciiDoc API のインストール方法と、日本語を処理した時に発生するユニコードエラーの対応について説明しています。

Pelican は、Python で書かれた静的なサイトジェネレータです。reStructuredText や Markdown を標準でサポートしています。

マークアップ言語に AsciiDoc を利用するために必要な、文書化されていない手続について説明します。

AsciiDoc API のインストール

Pelican で AsciiDoc を利用するには、AsciiDoc API をインストールする必要があります。 Markdown を利用するには pip を使ったインストールが可能ですが、AsciiDoc の場合は別途作業になります。

AsciiDoc API は asciidocapi.py ファイルの形で提供されています。Sourceforge から AsciiDoc のソースコードのアーカイブを解凍するとトップレベルに asciidocapi.py が見つかります。

私の環境は、virtualenv を使っていますので次の場所にインストールしました。 ~/.virtualenvs/(Pelicanを使う仮想環境名)/bin/asciidocapi.py

これで、ドキュメントのファイル名の拡張子を asc にすると、Pelican は AsciiDoc として認識し処理してくれます。

ユニコードエラーの問題

利用している Python 環境によっては、Pelican で日本語の文書を処理した時にユニコードのエラーが発生することがあります。これは既定のエンコーディングが utf-8 になっていないためです。

WARNING: Could not process ./mydoc.asc
'ascii' codec can't encode characters in position 20-22: ordinal not in range(128)
Done: Processed 1 articles and 0 pages in 0.40 seconds.

次のように、調べると既定のエンコーディングを調べることができます。

>>> import sys
>>> sys.getdefaultencoding()
'ascii'

asciidocapi.py を書き換える方法と、Python の環境設定ファイルを編集する方法があります。Python の配布用モジュールを開発している訳ではないので、今回は環境設定ファイルで対応しました。

設定は sitecustomize.py を編集します。 このファイルのありか次のように調べます。

>>> import sitecustomize
>>> sitecustomize.__file__
'/usr/local/lib/python2.7/site-packages/sitecustomize.pyc'

このファイルに次のような記述を追加します。

import sys
sys.setdefaultencoding('utf-8')

最後に、既定の設定が反映されているか確認します。次のように utf-8 になっていれば完了です。

>>> import sys
>>> sys.getdefaultencoding()
'utf-8'

文書化されていない Pelican での AsciiDoc 利用の方法はここまでです。 ここから先は、他のマークアップ言語と同じようにドキュメントの内容に従って使いこなしてください。