rmarkdownのYAMLヘッダ

T. Yoshiizumi

2017/03/04

＜目　次＞

1.　rmarkdownを試した環境

　筆者がrmarkdownを試した環境は下のとおり。

　当サイトの rptパッケージを導入している場合、上の環境がインストール済みです。

目次に戻る

2.　YAMLヘッダとは

　rmarkdownの原稿は、test.rmd のようなファイル名で保存します。

　その冒頭には YAMLヘッダというのを置くことができます。

　たとえば次のような記述形式です。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output: html_document
---

　文書の表題、筆者、日付が基本の三項目です。

　それに加えて、出力形式(output)も指定できます。

　outputの指定がなければ html_document が指定されたものと見なされます。

　　　　

　このヘッダ部分は、YAMLという仕様に即して書きます。

　YAMLは、構造を持つデータを表現・記録するための記述ルールです。

　配列やハッシュ(連想配列)などを表現できます。

　それらが入れ子構造になっていても大丈夫です。

　title: "Test Page" というのはハッシュです。

　rmarkdownは、このYAMLヘッダを解釈・整理して markdownの現行を生成し、
htmlなどの最終的な出力ファイルを作成します。

　つまり、test.rmd から test.md を生成し、最後に test.html を作成します。

目次に戻る

3.　指定できるoutputタイプ

　rmarkdownでは、pandocが対応する出力タイプのうち、いくつかを指定できます。

　html_document, pdf_document, beamer_presentation, word_document, rtf_document など。

　beamer_presentationは、LaTeXで作成するプレゼン用のpdfファイルです。

　word_documentは、MS-Word用のdocxファイルです。

　日本語を扱う場合、工夫が必要になるケースがあります。

目次に戻る

4.　YAMLヘッダのサンプル

　先に示した筆者の環境で、日本語処理できたYAMLヘッダを掲げます。

(1) html_document

　目次付きhtml出力の例です。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output:
  html_document:
    md_extensions: -ascii_identifiers
    pandoc_args: [
      "--toc",
      "--toc-depth=2"
    ]
---

　　　　

　md_extensions: -ascii_identifiers
日本語のhtmlファイルに目次(toc: TableOfContents)を盛り込むときは指定するのが無難。
pandoc_args: [ …… ]
pandocに引き渡すオプションを配列形式で書いています。
--toc：目次生成の指定、--toc-depth=2：目次に組み入れるヘッダレベルの指定(h1, h2 を組み入れる)。

　　　　

　pandocは、<h1>, <h2> などにID属性を付ける際、見出しの文字をそのままID属性にします。

　そして、目次を生成する場合は、そのID属性を手がかりにします。

　しかし、ascii_identifiers というオプションが指定されると、見出しの2バイト文字を取り除いたうえでID属性にします。

　日本語を扱うなら ascii_identifiers を無効にしておくのが無難ですが、rmarkdownライブ来がpandocを起動する際は、ascii_identifiers を有効にしてしまいます。

　それを無効にするため md_extensions: -ascii_identifiers を書きます。

目次に戻る

(2) pdf_document

　rmarkdownでは、pandoc + LaTeX でpdfファイルを生成できます。

　ここでは w32tex の lualatex を用います。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output:
  pdf_document:
    md_extensions: -ascii_identifiers
    keep_tex: true
    latex_engine: lualatex
    pandoc_args: [
      "--toc",
      "--toc-depth=2"
    ]
documentclass: ltjltxdoc
classoption: a4paper,12pt
---

　　　　

keep_tex: true
pdfファイルだけでなく、TeXの原稿も残したいときにこれを指定します。
latex_engine: lualatex
LaTeXのうち、lualatexを使うとの指定です。
documentclass: ltjltxdoc
TeXのドキュメントクラスの指定。lualatexで日本語文書を扱うときは、これをよく使うようです。
classoption: a4paper,12pt
クラスオプションで、用紙 A4サイズ、フォントサイズ 12ポイントを指定。

　　　　

　keep_tex を指定してTeXの原稿を残した場合、それを修正したうえで

lualatex test.tex [enter]

　上のようにコマンドを実行して、改めてpdfファイルを生成できます。

目次に戻る

(3) beamer_presentation

　beamerは、プレゼン用のファイルです。LaTeXによりpdfファイルとして生成します。

　見出しが切りかわると、それに応じてスライド(ページ)がかわります。

　日本語を扱うのに少々工夫が必要です。

　YAMLヘッダの一例は下のとおり。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output:
  beamer_presentation:
    keep_tex: true
    latex_engine: lualatex
    md_extensions: -ascii_identifiers-tex_math_single_backslash
    pandoc_args: [
      "-H", "luatexja.tex",
      "-V", "theme=Madrid",
      "-V", "colortheme=seahorse",
      "-V", "fontsize=14pt"
    ]
---

　　　　

　’luatexja.tex’ というファイルは、予め用意しておきます。次の２行からなるファイルです。

\usepackage{luatexja}
\hypersetup{unicode=true}

　これを pandoc の ‘-H’ オプションで、TeX原稿のヘッダ部に挿入します。

　これがないとpdfファイルから二バイト文字が抜け落ちてしまうようです。

［参考サイト：　 markdownの原稿を、pandocを使って、Texのbeamerを利用して、プレゼンスライドPDFに変換

　　　　

　今回、pandocのオプションをいろいろ指定しています。

theme=Madrid
表示テーマをMadridに指定。この場合のテーマは「書式」とか「表示形式」といった意味合い。
colortheme=seahorse
色のテーマをseahorseに指定。
fontsize=14pt
文字サイズを14ポイントに指定。

　上は、いずれも pandoc の ‘-V’ オプションで指定しています。小文字でなく大文字の ‘V’ です。

目次に戻る

(4) word_document

　MS-Wordのdocxファイルを生成します。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output:
  word_document:
    toc: true
---

　　　　

　toc: true があると目次が付きます。

　作成されたdocxファイルをWordで開こうとすると、下のメッセージが出ます。

この文書には他のファイルを参照するフィールドが含まれています。
この文書のフィールドを更新してもよろしいですか?

　これに「はい」で応答すると目次が挿入されます。

　目次では、各見出しごとにページ番号もつきます。

目次に戻る

5.　補足事項

　ちょっと便利だとおもった事柄、気になった事柄を記します。

(1) 見出しのナンバリング

　YAMLヘッダ部に number_sections: true を書くと、見出しに番号が付きます。

　たとえば下のように書きます。

output:
  html_document:
    md_extensions: -ascii_identifiers
    number_sections: true
    pandoc_args: [
      "--toc",
      "--toc-depth=2"
    ]

　　　　

　「この見出しには番号を付けたくない」という場合は、markdownの原稿中の該当の見出しのところで、{-} を行末に付加します。

### 見出しへのナンバリング {-}

　このナンバリングは、htmlだけでなくpdfなどでも有効です。

　ただし、word_document では機能しないようです。

目次に戻る

(2) LaTeXのBXjsclsパッケージのpandocモード

　LaTeXに bxjsarticle というドキュメントクラスがあります。

　日本語ドキュメントクラスの jsarticle を、lualatex, xelatex などでも使えるように修正を施したドキュメントクラスです。

　bxjsarticleクラスは、BXjsclsパッケージに含まれています。

　これにはpandocモードがあり、TeX原稿の冒頭に次ぎの１行を書いて指定できます。

\documentclass[pandoc,jafont=ipaex]{bxjsarticle}

　jsarticleの場合と同様、日本語文書が適切に処理されるようです。

　このpandocモードを利用するためのYAMLヘッダを掲げておきます。

---
title: "Test Document"
author: "Black Lady"
date: "2017-02-11"
output:
  pdf_document:
    keep_tex: true
    latex_engine: lualatex
documentclass: bxjsarticle
classoption: pandoc,jafont=ipaex,a4paper
---

　　　　

　BXjsclsパッケージにはスライド作成のための bxjsslideクラスもあります。

　これにもpandocモードを適用できるようです。

　先のYAMLヘッダの bxjsarticle を bxjsslide に変更します。

　すると、見出しごとにスライドが切り替わる形のpdfファイルができます。

［参考サイト］：　 TeX Wiki - BXjscls

目次に戻る

(3) word_documentと目次

　pandocでは目次に組み入れる見出しレベルを --toc-depth で指定できます。

　--toc-depth=2 とすれば h1, h2 だけが目次に組み入れられて、h3 以下は拾われません。

　また、toc-depth の指定がないときは、h3までが組み入れられます。

　しかし、word_document の場合、このpandocの仕様が適用されないようです。

　word_document だと、見出しレベル４以下も目次に組み入れられるようです。

　なんとか --toc-depth=2 を有効にできないか試しましたが、筆者のところでは成功していません。

　rmarkdownのYAMLヘッダ部の解説は、これくらいにします。

〜　以上　〜