Aya (Igarashi) Ozawa - @Ladicle
This posts is about hugo, ox-hugo, org, emacs and emacs.

ox-Hugo Cheat Sheet

Table of Contents

1 図、表、コードの導入と参照

画像や、テーブルはキャプションを付けたり、Code 1のように参照することができる。参照したい名前を #+NAME: <name> に設定すると、通常のorgリンクを使って [[<name>]] で参照できる。デフォルトでは、参照時に番号のみ表示されるが、Code 2のように変数を設定すると識別子まで展開することができる。

(setq org-blackfriday--org-element-string '((src-block . "Code")
					    (table . "表")
					    (figure . "Figure")))
Code 1: 識別子名の設定

また、Code 1のように識別子のカスタマイズも可能だ。他にも識別子を変更する方法がある。それは、言語設定をすることだ。ファイルのトップに #+language: jp のように記述すると、識別子がその言語で翻訳されて出力される。Code 2のように明示的に設定していた場合、自動翻訳は実施されない。

* COMMENT Local Variables                                       :ARCHIVE:
# Local Variables:
# org-hugo-link-desc-insert-type: t
# End:
Code 2: 識別子の展開オプション

SRCで指定した言語名もclass要素に配置してくれるので、CSS側で加工することも、Hilight.jsでハイライトすることもできる。他にも、行番号を表示するための設定もある。

1.1 図のAMP対応

Orgで挿入した図は、Hugoデフォルトのfigure shortcode形式で出力される。しかし、デフォルトのshortcodeは amp-img ではなく通常の img 要素が使われているので、自前で用意する必要がある。 対応方法は簡単で、 layouts/shotcords ディレクトリにCode 3のファイルを入れておけば上書きできる。一点、AMPは width と height の指定が必須の点には注意が必要だ。

<figure{{ if .Get "class" }} class="{{ .Get "class" }}"{{ end }}>

<amp-img src="{{ $.Site.BaseURL }}{{ .Get "src" }}"
	 alt="{{ .Get "alt" | defautl "" }}"
	 height={{ .Get "height" | default "400" }}
	 width={{ .Get "width" | default "640"}}></amp-img>

{{ if .Get "caption" }}
<figcaption>{{ .Get "caption" }}</figcaption>
{{ end }}

</figure>
Code 3: figure.htmlのShortcode

Code 4のように、図のプロパティとして #+attr_html を利用すると、widthなどの追加アトリビューションを設定することができる。図の場合は、captionもこちらで指定してもよい。

#+attr_html: :width 450px :height 300px :caption PlantUML Sequence
Code 4: 図のattribution設定

1.2 Chromaによるシンタックスハイライト

Hilight.jsによるシンタックスハイライトをよく見かけるが、AMPではこの手のJavascriptが利用できない。また、 Emacs Lisp 等のよく使うハイライトに対応していないので別の方法が求められる。幸いなことに、Hugoではchromaに対応しているので、ハイライト済みのHTMLを吐き出すことができる。

設定方法はshortcodeを利用する等いくつかの方法があるが、常時有効にするのであればCode 5のようにHugoの設定ファイルで指定するのが簡単だ。ハイライトのスタイルはchroma style garallyから確認することができる。

pygmentsUseClasses = true # ShortCodeを使わずに Markdown方式で出力する
pygmentsStyle = "pastie"  # Style
Code 5: config.tomlによるHugoのchromaオプションの有効化

他にも、行番号を表示させるオプションなど、さまざまなオプションが提供されている。詳しくは Syntax Highlighting | Hugo で解説されている。

2 Subtreeのプロパティと各種機能 [50%]

ox-hugoでは多くのプロパティが提供されているが、ドキュメントに網羅されていない。そのため、全体像を知るには ox-hugo.el あたりをみるのがオススメ。

TODO 2.1 DraftフラグをTODOタグで切り替える

Hugoにはその記事がDraftかどうかを示すフラグがあるが、ox-hugoのSubtree方式で出力した場合、 TODO タグでDraftフラグをon/offできる。ちなみに、 COMMENT タグを付けたSubtreeは出力されない。

DONE 2.2 プロパティによる目次とHUGOの制御

Code 6のようにプロパティで出力ファイル名、目次、セクション、タグを指定できる。 EXPORT_HUGO_CUSTOM_FRONT_MATTER の値は、記事毎のメタタグに追加されるので、Hugoの architype 等を使って独自拡張しているオプションはここで指定できる。

:PROPERTIES:
:EXPORT_FILE_NAME: ox-hugo-cheat
:EXPORT_OPTIONS: toc:3 num:t
:EXPORT_HUGO_SECTION: pages
:EXPORT_HUGO_TAGS: org-mode ox-hugo hugo
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :lang jp :twitter true
:END:
Code 6: 本記事のSubtreeに設定しているプロパティ

これらのプロパティは、Tree上位で設定したものを引き継げる。よって、カテゴリーやセクションごとにツリーを区切っていくとプロパティの記述量を減らすことができる。

3 文字スタイルとHTML

3.1 Markdownに変換されるスタイル一覧

Table 1のように、一般的な文字スタイルには全て対応している。Markdown記法に下線が存在しないため、 underline クラスが付与された要素が出力される。よって、このクラスに対して下線を表示するCSSを適用すればよい。

Table 1: Org記法とMarkdown、実際の表示の対応表
スタイル名Org記法Markdown記法表示
太字*bold**bold*bold
打ち消し線+strike-through+~strike-through~strike-through
斜字/italics/_italics_italics
下線_underline_noneunderline

3.2 引用する

引用にはQUOTEブロックが使える。よって、通常通り <q + TAB で展開できる。ただし、 <cite> 要素には対応していないので、追加したい場合は直接HTMLを追記する必要がある。

quote messagequote messagequote messagequote messagequote messagequote messagequote messagequote messagequote messagequote messagequote

Aya Igarashi p11, 2018

3.3 HTMLの制御とNoteブロックの追加

QUOTEブロックのように #+BEGIN_<XYZ>...#+END_<XYZ> の <XYZ> 部分に任意の文字列を付与すると、ブロック内のテキストが <div class=XYZ></div> 要素で囲まれて出力される。ただし、 subtree などの標準的なテキスト以外は追加することが出来ない。

これは注意事項を書くところです。

その他の方法で自由にHTML要素を追加したい場合は、 #+HTML: プロパティを利用できる。subtreeをHTML要素で囲みたい場合は、Code 7のように記述する。

#+html: <div class="wrapper"><div></div>
* subtree
text
#+html: <div>
Code 7: div要素でラップされたsubtree

3.4 リスト一覧

Org記法で使える順序あり/なしリスト、チェックリスト、定義リストは全て正常に出力できる。チェックリストは、もちろん disable の状態で出力される。

3.4.1 順序なしリスト

  • sample1
    • sample 1.1
    • sample 1.2
  • sample2

3.4.2 順序付きリスト

  1. sample1
    1. sample 1.1
    2. sample 1.2
  2. sample2

3.4.3 チェックリスト [1/2]

  • hoge
  • age

3.4.4 定義リスト

Apple
Red, Fruit, …
Orange
Yellow, Fruit, …

4 LaTex数式を埋め込む

MathJaxに対応している。LaTex数式を次ように \(F(x) = \sum_{n=1}^{N} \frac{1}{N}\) インラインでも、単独で埋め込むこともできる。インラインの場合は、Code 8のように $ で囲む必要がある。

$F(x) = \sum_{n=1}^{N} \frac{1}{N}$
Code 8: インライン記法

単独で埋め込む場合は、Code 9のように直接書き込むだけだ。 SRC ブロックで囲むと表示されなくなるので注意が必要。実際に出力された結果はの下の式に示されている。

\begin{equation}
\label{eq:1}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}
Code 9: 単独でLaTex数式を埋め込む

単体で埋め込むと次のようになる。ただし、ノーマルなMathJaxを使って表示しているのでAMPページだとエラーが出る。そのうちW3C MathMLに対応させたい。

\begin{equation} \label{eq:1} C = W\log_{2} (1+\mathrm{SNR}) \end{equation}

5 org-babelによるコードブロックの評価

ここでは、org-babelによる画像や図の生成について解説する。この章には含まれないが、iPythonを使った計算やグラフ出力も便利なのでセットアップしておきたい。

5.1 Graphviz, PlantUML, ditaaを使ったの出力

Graphviz, PlantUML, ditaaでは、Org側で書いた、コードブロックは出力有無は、 :exports オプションに左右される。 results の場合はResultタグ側で出力、 value の場合は元のコードが出力、 both の場合は両方出力される。Captionをつけるには、Result側にタグを付与する必要がある。リンクは LABEL or NAME が使用できる。

5.1.1 Graphviz

Figure 1: Graphviz

Figure 1: Graphviz

Figure 1は、Graphvizによって出力されたSVG形式のグラフを示している。 :exports を code のみにするとプロパティを示せないため、 , を使ってコードブロックの中にインナーブロックを追加している。また前述1の通り、図には幅と高さを指定している。

#+BEGIN_SRC dot :file dot-example.svg :exports none :cache yes
digraph {
  b [shape=box]
  a -> c [label="A-C", style=dashed]
  b -> c [label="B-C"]
}
#+END_SRC

#+CAPTION: Graphviz
#+LABEL: fig:foo
#+ATTR_HTML: :width 640px :height 250px
,[[file:dot-example.svg]]
Code 10: Orgの SRC ブロックの中に dot の SRC ブロックを入れた場合

5.1.2 PlantUML

Figure 2は、PlantUMLによって出力されたSVG形式のシーケンス図だ。(白黒: on, 影: off) 最近はUML以外にも電子工作クラスタにも便利なタイミング図や、ネットワーク図までなんでもテキストから図が起こせるようになっている。Real World PlantUML ではPlantUMLのさまざまなサンプルが参照できる。

Figure 2: PlantUML Sequence

Figure 2: PlantUML Sequence

5.2 R x ggplot2 によるSVG形式のグラフ出力

Rのプログラムと、グラフの両方を出力するように設定してある。実行結果はFigure 2の通り。SVGであれば現代の他端末に対応できるし、RやPythonを使ったナウい機械学習なブログも書きやすくなる。

library(ggplot2)
ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) + geom_point()  + theme_bw()

Figure 2: ggplots2で出力したグラフ

Figure 2: ggplots2で出力したグラフ

6 参考文献

  1. ox-hugo - Org to Hugo exporter
  2. org-modeのコードブロック(Babel)の使い方 - Misohena Blog
  3. グラフ描画ggplot2の辞書的まとめ20のコード – MrUnadon
  4. ESS - RjpWiki

  1. AMPに対応するため。 ↩︎

.

READ NEXT...

EMACS

org-captureのテンプレート ver. 2021

This posts is about org, org-capture, org-journal and emacs.
EMACS

独自URL Schemeの追加と、そのハンドラの実装

This posts is about go, emacs, hugo and macOS.
EMACS

コードリーティングの記録とOrg Capture

This posts is about org, code-reading, org-capture and emacs.