org syntax とはなんぞや？

#はじめに

みなさまこんにちは．[@takaxp](https://twitter.com/takaxp) です．

`Emacs Org mode` 使ってますか？ はい．私は使っています．

さて，今回は `Org mode` の基礎である `org syntax` についてまとめたいと思います．様々な機能が実装されている `Org mode` は，どこから手を付けてよいかわからず，多くの初心者が戸惑い，おそらくは沼や魔境に見えていると思います．しかし，土台になっているのは，プレーンテキストを装飾するための単純なシンタックスです．まずはそれを知るだけで十分です．その他の機能は，気になったところから徐々に使い始めれば良いと思います．

#org syntax

`org syntax` の公式の情報は，`Org mode` コミュニティの wiki である `wrog` に記載されています．なんと未だにドラフト版です．`Org mode` 全体が，[サグラダ・ファミリア](https://ja.wikipedia.org/wiki/%E3%82%B5%E3%82%B0%E3%83%A9%E3%83%80%E3%83%BB%E3%83%95%E3%82%A1%E3%83%9F%E3%83%AA%E3%82%A2)または[バベルの塔](https://ja.wikipedia.org/wiki/%E3%83%90%E3%83%99%E3%83%AB%E3%81%AE%E5%A1%94)であることをよく表しています．

[org syntax (draft)](https://orgmode.org/worg/dev/org-syntax.html)

この記事では，主に `Markdown` との対比ができる項目のみ扱います．また方言の多い `Markdown` ですが，ここでは [CommonMark](https://commonmark.org/)を対象とします．

#対応表

左が `Org mode` で右が `CommonMark` です．基本的に同じことができます．あら簡単．

<table>
 <thead>
  <tr>
   <th></th>
   <th>Org mode</th>
   <th>CommonMark</th>
  </tr>
 </thead>
 <tr>
  <td>斜体</td>
  <td>/Italic/</td>
  <td>*Italic*<p>or</p>_Italic_</td>
 </tr>
 <tr>
  <td>太字</td>
  <td>*Bold*</td>
  <td>**Bold**<p>or</p>__Bold__</td>
 </tr>
 <tr>
  <td>見出し1</td>
  <td>* Heading 1</td>
  <td># Heading 1<p>or</p>Heading 1<br/>=========</td>
 </tr>
 <tr>
  <td>見出し2</td>
  <td>** Heading 2</td>
  <td>## Heading 2<p>or</p>Heading 2<br/>---------</td>
 </tr>
 <tr>
  <td>リンク</td>
  <td>[[http://a][Link]]<br/><br/><p>なお，[[http://a]]とURLだけ入れるのも可．</p></td>
  <td>[Link](http://a)<p>or</p>[Link][1]<br/>︙<br/>[1]: http://a</td>
 </tr>
 <tr>
  <td>外部画像</td>
  <td>[[http://orgmode.org/img/org-mode-unicorn-logo.png]]<p>or</p>
[[https://orgmode.org][https://orgmode.org/img/org-mode-unicorn-logo.png]]
<br/><br/><p>なお，[[]]で括らない生のURLでもOK．</p></td>
  <td>![Image](https://commonmark.org/help/images/favicon.png)<p>or</p>![Image][1]<br/>︙<br/>[1]: http://orgmode.org/img/org-mode-unicorn-logo.png</td>
 </tr>
 <tr>
  <td>引用</td>
  <td>#+begin_quote<br/>Quote<br/>#+end_quote</td>
  <td>> Blockquote</td>
 </tr>
 <tr>
  <td>リスト</td>
  <td>- List<br/>- List<br/>- List<br/><br/><p>+ も使える．</p></td>
  <td>* List<br/>* List<br/>* List<p>or</p>- List<br/>- List<br/>- List</td>
 </tr>
 <tr>
  <td>番号リスト</td>
  <td>1. One<br/>2. Two<br/>3. Three<br/><br/><p>1),2),3) も使える．</p></td>
  <td>1. One<br/>2. Two<br/>3. Three<p>or</p>1) List<br/>2) List<br/>3) List</td>
 </tr>
 <tr>
  <td>水平線</td>
  <td>Horizontal Rule<br/>-----</td>
  <td>Horizontal Rule<br/>---<p>or</p>Horizontal Rule<br/>***</td>
 </tr>
 <tr>
  <td>コードブロック</td>
  <td>#+begin_src<br/># code block<br/>echo "hoge"<br/>#+end_src</td>
  <td>```<br/># code block<br/>echo "hoge"<br/>```<p>or</p>&emsp;# code block<br/>&emsp;echo "hoge"</td>
 </tr>
 <tr>
  <td>インラインコード</td>
  <td>~Inline code~ with equals</td>
  <td>`Inline code` with backticks</td>
 </tr>
</table>

## HTMLでのレンダリング例

Heading（見出し）がデフォルトでナンバリングされるのが大きな違いでしょうか．`Org mode` で書かれた文書は構造化文書ですから，出力時は当然のナンバリングです（個人の感想です）．

また，リンク形式では `[]` しか使わないので，`Markdown` のように `[]()` だっけ？ `()[]` だっけ？と迷うことがありません（URLが左なのは覚えましょう．え...）

なお，`[[URL]]`を用いて外部サイトの画像を埋め込む場合，画像の `alt` は，自動的にファイル名になります．`[[URL][alt]]` の形式では，HTML出力時に `img` タグではなく `a` タグでレンダリングされ，画像が組み込まれずにクリッカブルリンクになるので注意してください．`alt` を指定しつつ画像を組み込むには，`#+ATTR_HTML:` を用いればOKです．次節で紹介します．

<table>
 <thead>
  <tr>
   <th></th>
   <th>Org mode</th>
   <th>in HTML</th>
  </tr>
 </thead>
 <tr>
  <td>斜体</td>
  <td>/Italic/</td>
  <td><i>Italic</i></td>
 </tr>
 <tr>
  <td>太字</td>
  <td>*Bold*</td>
  <td><b>Bold</b></td>
 </tr>
 <tr>
  <td>見出し1</td>
  <td>* Heading 1</td>
  <td><h2 id="org1e860f9"><span class="section-number-2">1</span> Heading 1</h2></td>
 </tr>
 <tr>
  <td>見出し2</td>
  <td>** Heading 2</td>
  <td><h3 id="orge0919d1"><span class="section-number-3">1.1</span> Heading 2</h3></td>
 </tr>
 <tr>
  <td>リンク</td>
  <td>[[http://a][Link]]</td>
  <td><a href="http://a">Link</a></td>
 </tr>
 <tr>
  <td>外部画像</td>
  <td>http://orgmode.org/img/org-mode-unicorn-logo.png<p>or</p>
[[https://orgmode.org][https://orgmode.org/img/org-mode-unicorn-logo.png]]
</td>
  <td><img src="https://orgmode.org/img/org-mode-unicorn-logo.png" alt="org-mode-unicorn-logo.png" /><br />
  </td>
 </tr>
 <tr>
  <td>引用</td>
  <td>#+begin_quote<br/>Quote<br/>#+end_quote</td>
  <td><blockquote><p>Quote<br/></p></blockquote></td>
 </tr>
 <tr>
  <td>リスト</td>
  <td>- List<br/>- List<br/>- List</td>
  <td><ul class="org-ul"><li>List 1<br /></li><li>List 2<br /></li><li>List 3<br /></li></ul></td>
 </tr>
 <tr>
  <td>番号リスト</td>
  <td>1. One<br/>2. Two<br/>3. Three</td>
  <td><ol class="org-ol"><li>One<br /></li><li>Two<br /></li><li>Three<br /></li></ol></td>
 </tr>
 <tr>
  <td>水平線</td>
  <td>Horizontal Rule<br/>-----</td>
  <td><p>Horizontal Rule<br /></p><hr /></td>
 </tr>
 <tr>
  <td>コードブロック</td>
  <td>#+begin_src<br/># code block<br/>echo "hoge"<br/>#+end_src</td>
  <td><pre class="example">
# code block
echo "hoge"
  </pre></td>
 </tr>
 <tr>
  <td>インラインコード</td>
  <td>~Inline code~ with equals</td>
  <td><code>Inline code</code> with equals</td>
 </tr>
</table>

コードブロックの背景色がはみ出ているのは，記事へHTMLコードを強引に埋め込んでいるためですので，スルーしてください．

コードブロックの形式で `#+begin_src emacs-lisp` のように言語名を指定すると，言語ごとに適切なシンタクスハイライトの恩恵を受けられます．

### インライン画像の修飾

`alt` を指定しつつ，外部サイトの画像を出力に埋め込みたい場合は，`#+ATTR_HTML:` を使います．

```text
#+ATTR_HTML: :alt hoge
https://orgmode.org/img/org-mode-unicorn-logo.png
```

これを `Org mode` で HTMLエクスポートするだけです．`#+ATTR_HTML:`は`alt`以外にも，`width`や`height`などを指定できます．さらには `:style display:block` のようにスタイルも指定できるので，制御し放題です．

さらに，`#+caption:` を使うと，キャプションも付けられます．番号も振ってくれます．

```text
#+caption: ゆにこーん
#+ATTR_HTML: :width 100 :alt unicorn
http://orgmode.org/img/org-mode-unicorn-logo.png
```

<div class="figure">
<p><img src="http://orgmode.org/img/org-mode-unicorn-logo.png" alt="unicorn" width="100" /><br />
</p>
<p><span class="figure-number">Figure 1: </span>ゆにこーん</p>
</div>

### クリック可能な画像を埋め込む

```
[[https://orgmode.org][https://orgmode.org/img/org-mode-unicorn-logo.png]]
```

とすると，外部画像を埋め込みつつ，クリックすると指定したURL（ https://orgmode.org ）へ飛ぶリンクを生成できます．

<p><a href="https://orgmode.org"><img src="https://orgmode.org/img/org-mode-unicorn-logo.png" alt="org-mode-unicorn-logo.png" /></a></p>


### クリック可能なインライン画像を修飾する

前節2つを組み合わせると，もっとリッチになります．

```

#+caption: ゆにこーーん
#+ATTR_HTML: :width 100 :alt unicooorn
[[https://orgmode.org][https://orgmode.org/img/org-mode-unicorn-logo.png]]
```

<div class="figure">
<p><a href="https://orgmode.org" width="100" alt="unicooorn"><img src="https://orgmode.org/img/org-mode-unicorn-logo.png" alt="unicooorn" width="100" /></a><br />
</p>
<p><span class="figure-number">Figure 1: </span>ゆにこーーん</p>
</div>


## その他のシンタックス

上の表に登場しなかったシンタックスのうち，知っておいて良いものを紹介します．

<table>
 <thead>
  <tr>
   <th></th>
   <th>Org mode</th>
   <th>in HTML</th>
  </tr>
 </thead>
 <tr>
  <td>打ち消し線</td>
  <td>+Strike+</td>
  <td>
Strike
</td>
 </tr>
 <tr>
  <td>逐語</td>
  <td>=Verbatim=</td>
  <td><code>Verbatim</code></td>
 </tr>
 <tr>
  <td>チェックリスト（オフ）</td>
  <td>- [ ] List<br/>- [ ] List<br/>- [ ] List</td>
  <td><ul class="org-ul">
<li class="off"><code>[&#xa0;]</code> List 1<br /></li>
<li class="off"><code>[&#xa0;]</code> List 2<br /></li>
<li class="off"><code>[&#xa0;]</code> List 3<br /></li>
</ul></td>
 </tr>
 <tr>
  <td>チェックリスト（オン）</td>
  <td>- [X] List<br/>- [X] List<br/>- [X] List</td>
  <td><ul class="org-ul">
<li class="on"><code>[X]</code> List 1<br /></li>
<li class="on"><code>[X]</code> List 2<br /></li>
<li class="on"><code>[X]</code> List 3<br /></li>
</ul></td>
 </tr>
 <tr>
  <td>脚注</td>
  <td>hoge hoge[fn:1].<br/>[fn:1] yes you can.</td>
  <td><p>
hoge hoge<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>.<br />
</p>
︙
<div id="footnotes">
<h2 class="footnotes">Footnotes: </h2>
<div id="text-footnotes">

<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1">1</a></sup> <div class="footpara"><p class="footpara">
 yes you can.<br />
</p>
</td>
 </tr>
</table>


脚注のレンダリングが少々乱れていますが，あしからずご了承ください．またここには紹介していないシンタックスがまだまだありますので，興味がある方は [org syntax (draft)](https://orgmode.org/worg/dev/org-syntax.html) を訪れてみてください．

## Emacs上での見た目

今回紹介したシンタックスのうち，テキストのマークアップやリンク等は，見やすく加工されてバッファにレンダリングされます．次のような感じです．外部画像へのリンクはレンダリングできませんが，一度ローカルに保存すれば可能です．`#+ATTR_HTML:` も効きます．ここまで表現できて，それでも**プレーンテキスト**です．

![Screen Shot 2019-12-07 at 2.07.28.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12232/91420ed4-72fe-3d2d-efa9-a2eb65a02fb4.png)



#まとめ

この記事では，[CommonMark](https://commonmark.org/)と対比しながら，`org syntax` について述べました．これまでに`Markdown`とは異なる謎の形式で書かれたプレーンテキストを受け取ったことがあると思いますけど（ないか），それは `org syntax` だったかもしれません．今後は苦労なく読めるようになると思います．

それに，皆さん大好き [GitHub](https://github.com/) も，実は `Org syntax` に対応しています．次に作る新しいプロジェクトは，`README.md`ではなく，思い切って `README.org` にしてみましょう（例：[moom.el のREADME](https://github.com/takaxp/moom/blob/master/README.org) @軽いステマ）

最後に，本記事が [Visual Studio Code](https://github.com/vscode-org-mode/vscode-org-mode) や [Vim](https://github.com/jceb/vim-orgmode) でもサポートが進んでいる `Org mode` を使う足がかりとなれば嬉しく思います．

![org icon](https://orgmode.org/img/org-mode-unicorn-logo.png)Enjoy [Org mode](https://orgmode.org/ja/)!