Org-mode による HTML 文書作成入門

Org-mode 用のソースファイルの拡張子は .org です。 ファイル名は何でも構いませんが、デフォルトではそのファイル名が文書のタイトルになります。 Emacs で .org ファイルを開いたら、それで準備完了です。 これはテストなので、内容は空で構いません。

文書を HTML として出力し、それをブラウザで見るコマンドは C-c C-e b です。 これだけで、 .org から .html が生成され、それがブラウザで開かれます。 以下のような結果が出力されたでしょうか。 タイトルが "test" となっているのは、このサンプルのファイル名が test.org だからです。

HTML として出力するだけであれば C-c C-e h なのですが、 ほとんどの場合すぐに結果を確認したいと思うので、こちらを使うことはあまりないでしょう。

まず、文書に関する情報を記述します。 既に見たように、何も記述しなくても Org-mode は必要な情報を Emacs の設定などから自動的に抽出しますが、それでは都合が悪いことも多いでしょう。

例えばこのドキュメントの場合は、以下のような情報をソースの先頭に記述しています。

#+TITLE: Org-mode による HTML 文書作成入門
#+AUTHOR: MORIMOTO Ken
#+LANGUAGE: ja

英語の意味から分かると思いますが、上から順に、文書のタイトル、著者、言語を宣言しています。 もしメールアドレスを指定したい場合は以下のようにします。

#+EMAIL: user@example.com

基本的に文書は、見出しと本文で構成されます。 見出しは、行頭に '*' を書きます。 '*' の数によって見出しの大きさが変わり、数が多いほど見出しの扱いが小さくなります。 本文については、特別な書き方はありません。 空行は段落の区切りと見なされます。

以下が記述例です。 Emacs によって見出しに色付けが行われるので、プレーンテキストよりも読み易くなっています。

* 文書作成の流れ

  まず最初に、 Org-mode を使った文書作成の流れを概観します。

** Org-mode 用のソースを用意する

  Org-mode 用のソースファイルの拡張子は .org です。
  ファイル名は何でも構いませんが、デフォルトではそのファイル名が文書のタイトルになります。
  Emacs で .org ファイルを開いたら、それで準備完了です。
  これはテストなので、内容は空で構いません。

** HTML として出力する

  文書を HTML として出力し、それをブラウザで見るコマンドは =C-c C-e b= です。

見出しにポイントを合わせて TAB を押すと、その見出し以下の表示を Emacs 上で隠したり (閉じたり) 再表示させたり (開いたり) できます。 また、 S-TAB でソース全体の見出しの表示レベルを変更することができます。 Emacs で .org ファイルを開いた時には、大見出し以外は全て閉じられている状態なので、 ソース全体を確認するには S-TAB で再表示を行う必要があります。 最初は慣れないかもしれませんが、そのうち便利に感じるようになると思います。

文字を装飾する記法もいくつか用意されています。 残念ながら class などが指定されていないので、スタイルシートで装飾することが難しくなっています。 (Org-mode のバージョンによって HTML での表現は異なる可能性があります。)

.org での書き方	HTML での表現	表示結果
*太字*	<b>太字 abc</b>	太字 abc
/斜体/	<i>斜体 abc</i>	斜体 abc
_下線付き_	<span style="text-decoration:underline;">下線付き abc</span>	下線付き abc
+取消線付き+	<del>取消線付き abc</del>	取消線付き acb
=コード=	<code>コード abc</code>	コード abc
~等幅~	<code>等幅 abc</code>	等幅 abc

Org-mode は、ソース中の 'http://example.com' のような記述を自動的にハイパーリンクに変換しますが、 URI の代わりに分かりやすい文字列を表示したいなどの場合は、

[[リンク先][表示文字列]]

という記法を用います。 例えば、

[[http://www.google.co.jp][Google 日本]]

と書けば、「Google 日本」のように HTML で出力されます。 ただ、 Emacs で編集していると、ハイパーリンク用の記法で書いた瞬間に Emacs 上での表示も

と書けば、「Google 日本」のように HTML で出力されます。

という風に変わるので、最初は戸惑うかもしれません。 このように表示が変わった状態でも、表示文字列の編集は普段通り行うことができますし、 リンク先については C-c C-l で編集できます。 あるいは、ハイパーリンクの後ろにポイントを合わせてバックスペースを押すことで、 リンク記法の最後の ']' を削除することもできます。

画像を埋め込む場合は、

[[file:ファイルのパス]]

という、ハイパーリンクに似た記法を用います。 これもハイパーリンク同様、書いた瞬間に

file:img/icon.png

のように Emacs 上の表示が変わります。

もし、 HTML の img タグに属性を追加したい場合 (典型的には alt 属性) は、以下のような特別な書き方をします。 属性はいくつ指定しても構いません。

#+ATTR_HTML: alt="代替文字列" class="クラス名"
file:img/icon.png

リストは、各要素の先頭に決まった文字列を書くことで表現し、リストの深さは空白によるインデントで表現します。

数付きのリストの場合は、"1. " や "2. " のように書きますが、 HTML 出力時には数字自体は無視され、必ず 1 からの連番となります。 数字無しのリストの場合は "- " と書きます。 いずれも、 空白を挟んでから 内容を記述することに注意してください。

以下に例を示します。

1. January
   - 元旦
   - 成人の日
2. Feburuary
   - 建国記念の日

上記のように書くと、以下のように出力されます。

1. January
   • 元旦
   • 成人の日
2. Feburuary
   • 建国記念の日

行頭が '|' で始まる行はテーブルと見なされます。 テーブルの区切りも '|' です。 また、行頭が "|-" で始まる行はテーブルの区切りで、ヘッダ、ボディ、フッタを分離します。

以下に例を示します。

|ヘッダ A|ヘッダ B|
|-
|値 A|値 B|

このように書いたものは、以下のようなテーブルとして出力されます。

ヘッダ A	ヘッダ B
値 A	値 B

Org-mode でテーブルを編集していると気づくかもしれませんが、 テキストで見てもテーブルに見えるように自動整形する機能があります。 上のソースの、テーブルのどこかで TAB を押すと、以下のように整形されます。

| ヘッダ A | ヘッダ B |
|----------+----------|
| 値 A     | 値 B     |

フォントが等幅であれば、きちんと罫線が繋がっているように見えるはずです。

プログラムソースを書く場合は #+BEGIN_SRC と #+END_SRC を使い、以下のようにモード名も記述します。

#+BEGIN_SRC c++
 #include <iostream>

 int main(int argc, char** argv)
 {
     std::cout << "Hello, world." << std::endl;
     return 0;
 }
#+END_SRC

すると、指定したモードによって出力時に色付けが行なわれ、以下のように出力されます。

#include <iostream>

int main(int argc, char** argv)
{
    std::cout << "Hello, world." << std::endl;
    return 0;
}

勿論、プログラム用のモードに限らず、"fundamental" や "text" を指定しても構いません。 ただし、色付けには別途 htmlize.el が必要です。

HTML を直接記述したい場合は "#+HTML: " に続けて書くか、 #+BEGIN_HTML と #+END_HTML を使います。 単純なタグであれば、タグの前に '@' を付けることでエスケープもできます。

Hello, @<strike>world@</strike> Japan.

#+HTML: <span class="foo">HELLO</span>

#+BEGIN_HTML
 <div class="bar">
   Hello, world.
 </div>
#+END_HTML

HTML に出力されないコメントを書きたい場合は、行頭に '#' を書くか、 インデントされた行頭 (行頭でも可) に "#+ " (空白が必要なことに注意) を書くと、 その行全体が無視されます。

出力のオプションは、以下のように書きます。

#+OPTION オプション:値 オプション:値 ...

オプションには以下のようなものがあります。 他にも色々あるのですが、このドキュメントの読者に必要そうなものだけをピックアップしました。 より詳しくは info を参照してください。

オプション	意味
H	どのレベルまでを見出しとし、どのレベル未満をリストとするか (1 〜)
num	見出しに番号を付けるかどうか (nil / t)
toc	目次を出力するかどうか、どのレベルの見出しまで目次に載せるか (nil / t / 1 〜)
^	'_' を下付き文字列の開始記号とするかどうか (nil / t / {})
author	著者情報を出力するかどうか (nil / t)
creator	出力ツール (Emacs と Org-mode) 情報を出力するかどうか (nil / t)
timestamp	タイムスタンプを出力するかどうか (nil / t)

このドキュメントでは、以下のように指定してあります。

#+OPTIONS: ^:nil toc:2

Org-mode の出力する HTML ソースは、スタイルシートで装飾しやすいように、 適宜 id や class が指定されています。 使用するスタイルシートを設定するには、ソースの中に以下のように記述します。

#+STYLE: <link rel="stylesheet" type="text/css" href="スタイルシートのパス" />

このドキュメントでは、スタイルシートについての説明は行いません。 スタイルシートについての知識がなく、それでも文書作成を急いでいる場合は、 ひとまず このドキュメントのスタイルシート をそのまま使っておけば、 このドキュメントと同じデザインにはできます。

少なくともこのドキュメントを作成している Org-mode では、 思い通りの場所に思い通りの文字を書けないことがあります。 例えば、テーブルの中に '|' を書くと、どうしてもセルの区切りだと見なされてしまうので、 '|' を書くことができません。

HTML では、" " の様に文字コードで文字を表現することができるので、 '&' さえなんとか HTML に出力できれば、任意の文字コードを表現できるということになります。 しかし、当然 Org-mode が '&' を '&' に変換してしまうので、 HTML 出力後のフックを利用して、逆変換するようにしてみました。

;; .org ファイル中の "@&" という文字列を、 HTML 出力時に "&" に置換する。
;; つまり、テーブルの中で '|' を使いたければ "@|" と書いておけばいい。
(add-hook 'org-export-html-final-hook
          '(lambda () (perform-replace "@&" "&" nil nil nil)))

このドキュメントのソースを ダウンロード できるようにしておきます。 参考になれば幸いです。