タグ: Markdown

Markdown でビジネス文書を作成する

ソフトウェア, , , , コメントを残す

まとめ

  • Pandoc’s Markdown という一方言には::: という汎用Divに対応する記法がある。
  • {markdown, latex} → html は pandoc のみでできる。別途 css を用意するといい。
  • {html, latex} → markdown は pandoc のみでできる。
  • {html, markdown} → latex はフィルタが必要。別途 sty を用意するといい。

ビジネス文書

しばらく前に「公文書を Markdown で」という話題があった。図入りの面倒くさいものや白書のような普通の書籍ほどの長大なものや法律の条文のような特殊なものは別として、圧倒的に多いであろう1枚ペラ程度の通達の類の文書には、 Markdown はとても向いていると思う。簡単なものほど Word のような高機能文書作成ソフトを使わずに Markdown で済ませたい。

この様式[1]は、役所が作成する公文書[2]から会社、さらには小学校や PTA、町内会までよく浸透している。

しかし Markdown では、この類の文書の様式に欠かせない右寄せ(右揃え)ができないのが最大のネックだ。意味と見た目の分離という観点から言えば右寄せ(右揃え)は見た目なのだが、ここではもうそう呼ぶ ことにする。

Markdown

機能を絞り込んで簡潔であることが Markdown の特長なのだから、あれもこれも盛り込んでいけば最初から HTML を使えばいいとなって元も子もない。とは言え不満はなんとかしたい。Markdown で書きながらも最終的には HTML にすることを想定して直接 HTMLタグ (<div style="text-align:right">)を書いてしまうという手段もあるのだが、せっかくの Markdown なのだし他の形式への変換も考えるとなるべくそういうことはやりたくない。

ここは Markdown 記法に HTML の汎用タグ <div> や <span> を表せるものがあれば万能なのになあ……と思っていたら、Pandoc’s Markdown という一方言にはこれが存在していることに今さらながら気がついた。

Pandoc の Markdown 拡張

Pandoc’s Markdown という一方言には::: という汎用の Div に対応する記法がある。ここでは触れないが、汎用の Span に対応する []{} 記法もある。

この記法は Pandoc で考案されたようだ[3]。他の方言ではあまりサポートされていないようだ。HackMD (CodiMD, HedgeDoc) では ::: はやや違った意味にされ、記法も違い限定された語だけしか使えないようだ。

汎用タグを使いすぎれば意味と見た目の分離が台なしになることは解っているのだが、最終手段として便利であることは間違いない。

例

たとえばファイル名 input.md に、Pandoc’s Markdown で書く。

::: {.myaddress}
○△□町会\
会長 ▼▲ ■◆
:::

Markdown から HTML へ

pandoc の標準機能で、特に何もしなくてもいい。コマンドラインで

pandoc --from markdown input.md -to html -o output.html

これにより作成される output.html は次のようになる。

<div class="myaddress">
<p>○△□町会<br />
会長 ▼▲ ■◆</p>
</div>

つまり、Markdown で書いた {.myaddress} がクラス名になる。このクラス名に対応する CSS は別途用意しておく。たとえばファイル名 myaddress.css に

.myaddress {
        text-align: right;
        text-indent: 0pt;
}

と書いておき、コマンドラインで

pandoc --from markdown input.md --to html --output output.html --css myaddress.css --standalone

として利用する。スタイルシートへのリンクがドキュメントヘッダに含まれるため、–standalone オプションも同時に付ける必要がある。

Markdown から LaTeX へ

出力形式を LaTeX とすると、::: は除去されてしまう。つまりコマンドラインで

pandoc --from markdown input.md --to latex --output output.tex

とすると、作成されるファイル output.tex は次のようになる。

○△□町会\\
会長 ▼▲ ■◆

pandoc の作者によるフィルタの例 latexdivs.py を使う[4]と、出力を

\begin{myaddress}

○△□町会\\
会長 ▼▲ ■◆

\end{myaddress}

のようにできる。これを実際に LaTeX で処理するには、 myaddress 環境を別途定義しておく必要がある。たとえば myaddress.sty に

% myaddress
\newenvironment{myaddress}
{\begin{flushright}}
  {\end{flushright}}

と書いておき、コマンドラインで --include-in-header で読み込ませる。

pandoc --from markdown input.md --to latex --output output.tex --include-in-header myaddress.sty --standalone

これにより作成される出力ファイルの内容は

\documentclass (略)
  (略)
% myaddress
\newenvironment{myaddress}
{\begin{flushright}}
  {\end{flushright}}
  (略)
\begin{document}

\begin{myaddress}

○△□町会\\
会長 ▼▲ ■◆

\end{myaddress}

\end{document}

のようになる。

形式の相互変換

以上、markdown → {html, latex} の例を示した。

自分のよく使う markdown, html, latex の相互変換についてまとめると、

  • {markdown, latex} → html は pandoc のみでできる。別途 css を用意するといい。
  • {html, latex} → markdown は pandoc のみでできる。
  • {html, markdown} → latex はフィルタが必要。別途 sty を用意するといい。

となる。

具体的な例

変換された html で利用する CSS ファイル
business.css
latex 出力のための pandoc フィルタ
business_md.py
latex 出力が利用する sty ファイル
business.sty
入力ファイル (markdown)
business-sample.md
pandoc --from markdown --to html --css business.css --standalone --output business-sample.html business-sample.md での出力ファイル (html)
business-sample.html
pandoc --from markdown --to latex --filter=./business_md.py --include-in-header business.sty --standalone --output business-sample.tex business-sample.md[5]での出力ファイル (latex)
business-sample.tex
pandoc --from markdown --to pdf --filter=./business_md.py --include-in-header=./business.sty --output business-sample.pdf business-sample.md[6]での出力ファイル (pdf)
business-sample.pdf
  1. 英文レターの形式を調べると、アメリカ式「フル・ブロック・スタイル」とイギリス式「フル・インデント・スタイル」が見つかる。日本のいわゆるビジネス文書はこのイギリス式「フル・インデント・ス タイル」にとてもよく似ている。特に電磁的文書ならアメリカ式がとても楽だし合理的だと思うのだが、なんと言っても理屈ではない習慣だからそう簡単に廃れることはないだろう。↑
  2. 検索すると多くの自治体の規程が見つかる。たとえば墨田区や佐伯市など。↑
  3. Syntax for divs↑
  4. サンプルのフィルタ latexdivs.py をそのまま使うには、入力ファイルのクラス名を書くところに .latex を加えておく必要がある。つまり input.md は ::: {.latex .myaddress} のように書く。↑
  5. PDF に変換させるには、オプションはこれだけでは実は足りず、ここの例では --pdf-engine=lualatex -V documentclass=bxjsarticle -V classoption=pandoc -V classoption=jafont=auto -V indent=1zw -V pagestyle=empty を加えている。↑
  6. 前註に同じ。↑

CSS で見出し(h1, h2, …)に連番を付ける

ソフトウェア, コメントを残す

検索すると似たようなタイトルでたくさんの記事が見つかります。今さら……な話題ですが、それらを参考に試行錯誤して、次のような CSS になりました。

よく見かける例だと、それぞれの見出しでひとつ下の階層のカウンターだけをリセットしているのが多いのですが、それだと h2 の次に(h3 がなくて) h4 が来るような場合にうまくいきません。そういう文書が悪いとも言えますが。

Chrome と Firefox で異なる結果になったりして、結局こうなりました。counter-set を紹介している記事はほとんど見かけません。見つけたのはこの質問と回答くらいで、回答者が仕様を説明してくれているのはとても参考になりました。仕様の EXAMPLE 22 は Firefox では正しく再現されません。

【2022年4月18日追記】現時点での Safari や iOS 上のブラウザー(Webkit)では counter-set が実装されていないため、下記ではうまくいかないようです。【追記終わり】【2023年12月12日追記】Safari や iOS 上のブラウザー(Webkit)に counter-set が実装されたようです。現時点でまだ実際に動作を確認していませんが。【追記終わり】

padding で字下げをしています。番号の書式は「公用文作成の考え方」を参考にしました。\a0 (non-breaking space)をいくつか入れているのは、連番をカタカナとしたので、見出しそのものの内容がカタカナで始まっている場合にある程度あいだが開いていないと混乱するからです。

body {
    counter-reset: chapter section subsection subsubsection paragraph subparagraph;
}

h1 {
    counter-set: section subsection subsubsection paragraph subparagraph;
}
h2 {
    counter-set: subsection subsubsection paragraph subparagraph;
    padding-left:1em;
}
h3 {
    counter-set: subsubsection paragraph subparagraph;
    padding-left:2em;
}
h4 {
    counter-set: paragraph subparagraph;
    padding-left:4em;
}
h5 {
    counter-set: subparagraph;
}

h1::before {
    counter-increment: chapter;
    content: counter(chapter, upper-roman) "\a0\a0\a0\a0";
}
h2::before {
    counter-increment: section;
    content: counter(section, decimal) "\a0\a0\a0\a0";
}
h3::before {
    counter-increment: subsection;
    content: "(" counter(subsection, decimal) ")\a0\a0\a0";
}
h4::before {
    counter-increment: subsubsection;
    content: counter(subsubsection, katakana) "\a0\a0\a0\a0";
}
h5::before {
    counter-increment: paragraph;
    content: "(" counter(paragraph, katakana) ")\a0\a0\a0";
}
h6::before {
    counter-increment: subparagraph;
    content: counter(subparagraph, upper-alpha) "\a0\a0\a0\a0";
}

きっかけは Markdown でした。最近、Firefox なら拡張機能 Markdown Viewer Webext 、Chrome なら拡張機能 Markdown Preview Plus などを使って、手元で Markdown で書いたものをブラウザーで眺めることがしばしばあります。その際に、この文書は見出しに連番がほしいよなあなどと思ったのです。

ここに挙げた2つの拡張機能は CSS を追加できるので、そこにこれを書いてもいいですが、そうすると Markdown なら全て連番付き見出しになってしまいます。拡張機能 Stylus で、好きなときに入れたり切ったりすることにしました。もちろん Markdown のプレビューだけではなく、あらゆるサイトを見る際に適用できます。