reStructuredTextで好き勝手にHTMLを書く方法

python

(第1回)Zope/Plone開発勉強会 成果。


今は私は、記事を主に、reStructuredTextで書いているけど、
HTML出力用の構文ではないから、その表現力に不満がある。
特に、テキストエディタのサイトを作っているのに、
ソースのハイライトや、正規表現指定で部分強調や、<kbd>タグを使えないのが不満だった。


俺はもっと好き勝手な表現を使いたいんだ・・・！！

raw-htmlディレクティブ

raw-htmlディレクティブを使えば、直接、HTMLを書くこともできるけど、
これだと場所を取っちゃうから、頻繁に使うのには向いていない。保守性が低くなる。

.. raw-html::

    HTMLを含んだコードを直接記述
    HTMLを含んだコードを直接記述
    HTMLを含んだコードを直接記述
    この機能を動かすには、 <kbd>A</kbd> と入力して下さい。

まとまった文を書くなら、この方法でも良いのだけど。

置き換え

多分、FAQ、改行の<br>を入れる方法として、置き換えを使う方法がある。


こんな感じで置き換えを定義して、

.. |KBDA| raw:: html

    <kbd>A</kbd>


本文では、こう書く。

この機能を動かすには、 |KBDA| と入力して下さい。


すると、次のように変換される。

この機能を呼び出すには、 <kbd>A</kbd> と押下してください。


ただ、この方法は使おうとする表現の種類が多い場合は、
それぞれに定義をつくる必要があるので面倒なのですね。使いづらいのですね。

raw-htmlなRoleを定義

docutilsのオフィシャルサイトみてたら、
次のようなことができることがわかった。


このようにRoleを定義して、

.. role:: raw-html(raw)
   :format: html


本文ではこう書く、という方法。

この機能を呼び出すには、 :raw-html:`<kbd>CTRL-P</kbd>` と押下してください。


短く書けて、
汎用性が高くて、
いろいろできる。


rawはデフォルトでは制限されていることが多いけど、
Ploneの設定を弄って、rawを有効にできる環境の人なら、これで充分すぎますよね。


いやー、良かった。良い方法を知ることができましたよ。