WordPressの記事内でMarkdown 記法を使うためのプラグインです。この記事もMarkdownで書いています。
「WordPress.com で Markdown 記法」と同等のことが個人でインストールしたWordPressでできます。
必要環境
- PHP5.3以上
- WordPress3.1以上
インストール方法
以下のリンクから最新のバージョンをダウンロードして wp-content/plugins/wp-gfm に配置してください。
GitHub Flavored Markdown for WordPress
デフォルトのままでも使えますが、設定 > WP GFM からカスタマイズが可能です。
利用方法
ショートコードで囲むとその中の内容が変換されます。ショートコードは[markdown] と [gfm] の2種類あり、それぞれ変換方法が異なります。v0.2以降から [markdown] の利用を推奨しています。
プラグインは投稿ページにショートコードを入力するボタンを提供します。変換したいテキストを選択状態にしてボタンを押すことでショートコードで囲むことができます。
Markdown記法 (推奨)
[markdown] を使うとPHP-Markdown を拡張したクラスを使い変換を行います。基本的なMarkdown記法に加えて Table や Fenced Code Blocks が使えます。
[markdown] の変換ではコードブロックのシンタックスハイライトは行いませんが、コードブロックの出力方法を設定からテンプレートで設定できます。デフォルトでは以下のようになっており、google-code-prettify を別途WordPressに導入することでシンタックスハイライトが可能になります。
<pre class="prettyprint lang-{{lang}}" title="{{title}}">{{codeblock}}</pre>
GitHub Flavored Markdown 記法
[gfm] をを使うと GitHub Render API などGitHub Flavored Markdown 記法が使えるウェブサービスを使って変換を行います。注意点としてウェブサービスとの通信速度が表示速度に影響します。
変換に使うウェブサービスのURLは設定できます。デフォルトは GitHub Render API になっています。しかし、GitHub Render API はアクセス回数制限があるため別途変換サービスを構築することが必要です。通信速度を考えるとWordPressと同じサーバ上に構築するのが現実的です。
背景や経緯など
紆余曲折している部分があります。
- 名前に反して
[gfm]ではなく[markdown]を推奨 - GitHubでの公開
Markdown記法を推奨していること
当初は [gfm] がメインのつもりだったためプラグイン名もそうなっているのですが、このブログではあまり [gfm] を使っておらず、[markdown] の使用が中心になっています。
[gfm] は外部のウェブサービスを使うためパフォーマンスに問題があります。トップページなど複数の記事を表示する場合に、例えば5つの記事で [gfm]を使っていると5回外部のウェブサービス に接続することになりページの表示スピードに大きく影響することがわかりました。実際 heroku に変換サービスを構築して使っていたのですが heroku はアクセスがないと眠ってしまうことも災いして PHP がタイムアウトするまで待たされた挙句タイムアウトして変換も失敗するという悲しいことが起きたりもしました。
その後 GitHub Flavored Markdown を使いたいわけではなく、Markdownに加えてTableとFenced Code Blocksが使えればよいこと気が付き PHP-Markdownクラスを拡張するという方向転換をしています。そういった訳で [markdown] の利用を推奨しています。
GitHubでの公開
最初は [markdown] はオプション扱いで普通のMarkdownを使いたい人は Composer というPHPの依存管理ツールで自分で PHP-Markdown のライブラリをセットアップしてもらう配布方法でした。PHP-Markdown が名前空間を使っており PHP5.3以上の環境が必要だったこともオプションの理由の１つです。
導入方法が難しいのでWordPressプラグインディレクトリじゃないほうが良いと判断してGitHubを選択しました。
その後 [markdown] がメインになり、PHP-Markdown のライブラリを同梱して導入方法は簡単になったのですが、
WordPress Github Plugin Updater というGitHub上で公開したWordPressプラグインの自動更新機能を組み込んだり、GitHubでSTARをつけてもらったり、Pull-Requestをもらったり、IssueでやりとりができたりとやはりMarkdown使いたいのはエンジニアの人が中心でGitHubでの運用が機能しているのでWordPressプラグインディレクトリに移動せずそのままにしています。
そんなわけでプラグイン名を変えてWordPressプラグインディレクトリに移動するという考えもあるのですが、キッカケがなく [markdown] を GitHub Flavored Markdown に近づけるという目論見もあったりしてそのままになっています。
wp-gfm