Chienomi

PureBuilder Simply改良: WordPressインポートの強化

開発::web

序

2022年を気持ちも新たに迎えるため、Chienomiは少しリニューアルを行った。

わかりやすいところでは、メニュー関連がすべて日本語になった。 英語だと分からないのかな、と思われる行動がかなり見受けられたためだ。 また、特に英語にしておく理由もなかったため修正した。

「関連記事」という機能を追加した。 これ自体は大したことではないのだが、その対象を古い(WordPressの)記事まで拡大したことで実は大きな変更となっている。

WordPressの記事のメタデータや内容を上書きできるようにするため、pbsimply-wpimporterが従来、強引にHTMLファイルを出力していたところ、PureBuilder Simplyによって処理されるソースファイルとして出力するように変更された。 (develブランチ)

これを実現するため、PureBuilder Simply自体も「分離されたメタデータのサポート」「拡張子を問わないソースファイルの処理オプション」などを追加した変更を加えた。

なお、PureBuilder SimplyはPandoc以外のエンジンをサポートするような変更が計画されており、この関係でコードの大幅なリファクタリングを予定している。 この変更を先に取り込むかどうかは未定。

PureBuilder Simply WP Importer

PureBuilder Simply WP ImporterはPureBuilder Simplyで構築されたサイト上にWordPressの記事を取り込むためのスクリプトである。

従来は予めPureBuilder Simplyによって生成されたHTMLファイルに記事本文を埋め込むというような形式であり、Buildディレクトリに出力を合成していた。 その生成過程でPureBuilder Simplyを使うため、無関係というわけではないが、無理やり混ぜ込んでいるに過ぎないものではあった。WordPressの記事をPureBuilder Simplyで直接管理できるわけではないからだ。

今回の変更で、WP ImporterはPureBuilder Simplyのソースファイルを出力するようになった。つまりSourceディレクトリに対して出力する前提になった。

これを実現したのは、Pandocが--metadata-fileという別ファイルのメタデータを取り込む機能を持つようになったためだ。 従来もそのようなことは不可能ではないが、割と汚い形で実現するものであった。

今回の変更では、WP Importerはメタデータファイルと記事本文を出力する。 メタデータファイルはWordPress記事のエクスポートデータに基づいてセットされるものであり、記事本文はHTMLまたはplain(通常Markdownとして解釈される)のファイルである。 従来、PureBuilder Simplyはメタデータを必須とすることもあり、MarkdownまたはReSTructured Textに制限されていた。 だが、分離されたメタデータファイルにメタデータを書くことができ、またソース形式の指定もできるため、-Xオプションによってこの制限を除外できるようになった。

基本的な使い方

まず、WordPressから記事のエクスポートを行い、XMLファイルを得る。 (例えばchienomi.WordPress.2019-10-13.xmlである)

これを適当なエクスポート処理用のディレクトリに配置する。

そしたらwp-importer.yamlを書く。 通常はoutdirとsourcefileだけ書けば良い。

outdirは出力するベースディレクトリを書く。 sourcefileはエクスポートファイルのパスだ。

こんな感じ。

---
outdir: ../Source
sourcefile: "chienomi.WordPress.2019-10-13.xml"

それ以外についてはREADMEを読んでほしい。

あとはwp-importer.rbを実行するだけで良い。

オーバーライド

overrideはエクスポートファイルに手を加えることなく、WordPress記事を編集するための機能だ。

巨大なファイルであるエクスポートファイルの編集は骨が折れるので、そのようなことをしなくても管理しやすい形でWordPress時代の記事に手を加えられるようにしている。

ただし、このオーバーライドは部分的な修正ではなく、全体の修正を意図していることに注意してほしい。 特定のデータだけを更新することはできるが(例えばメタデータを追加できる)、記事本文を更新する場合はその全文が必要である。

方法はおおまかに2つあり、YAMLで書く方法とMarkdownで書く方法がある。 YAMLで書く場合は./override.yamlにまとめて書くか、./override.d/以下に分けて書く(自動的にマージされる)かを選ぶことができる。

ここでは例としてhttps://example.com/archives/x/y/100という記事をオーバーライドする方法について説明しよう。

記事のパスは、ドメイン部を除外した/archives/x/y/100となる。 もしpathprefixを設定している場合はそれが追加されるが、通常は必要ないはずだ。 (サーバーがこれらのファイルを直接デリバリーできない場合、使うと便利かもしれない。)

この記事のタイトルを修正したい場合は、YAMLファイルに次のように書く。

---
/archives/x/y/100:
  title: ほげほげ記事

overrideの内容はマージされるため、該当のキーだけを設定すれば良い。

本文を書き直したい場合はarticle_bodyに書く。

---
/archives/x/y/100:
  title: ほげほげ記事
  article_body: |-
    # ほげ

    ほげほげ

    ほっげほげ

元記事はHTMLで書かれていたが、今回はReSTで書いた、というような場合はinput_formatを指定することで元記事と異なるソース形式を指定できる。

---
/archives/x/y/100:
  title: ほげほげ記事
  input_format: rst
  article_body: |-
    ###################
    ほげ
    ###################

    ほげほげ

    ほっげほげ

記事をMarkdownで書き直す場合はMarkdownファイルで書くのが便利だ。 この場合マージされるのはfrontmatterだが、特別なものとしてwp_pathというキーが必要になる。 これはoverrideされる対象記事を指定するために必要とされるものである。

---
wp_path: /archives/x/y/100
title: ほげほげ記事
---

# ほげ

ほげほげ

ほっげほげ

ちなみに、自動的にwpimported: trueがセットされ、overrideされた場合はwpoverrided: trueもセットされる。 この機能を使い、より自然な形でoverrideを行えるようになり、またインポートされた旧記事を明記することができるようになった。

むすび

WordPressのユーザーが、よりPureBuilder Simplyに移行しやすくなった。

以降後の編集に関しては特殊なテクニックを要したが、それもなくなり、実用的だ。

まだWordPressを使っている方も、これを機にPureBuilder Simplyを使ってみてほしい。