見出し画像

Markdownあれこれ

((void*)0)

マークダウンってご存知ですか。便利ですよね。
私はドキュメントを書くこととコードを書くことを仕事にしていますが、売り物のドキュメントでない限りは、専らマークダウンでドキュメンテーションしています。新人の皆さんには、WordやExcelの使い方同様に、マークダウンの書き方も教える様になってきました。教えるというか、マークダウンで書いたものしか見せないので、新人の方たちもそれに合わせざるを得ない状況なわけです。
今日はマークダウン関連の日常をあれこれ書いてみたいと思います。

なぜMarkdownか

理由その１：テキストファイルだから

私がマークダウンで書く最大の理由は、テキストファイルだから、です。テキストファイルだと何故良いのか？履歴管理と検索・加工処理が楽だから。テキストファイルで書くと、GitやSVN（10年近く使っていませんが）で管理出来る（バイナリも管理は出来ますがw）様になり、何をいつ誰が直したのか、簡単に管理できるようになりますね。元に戻すのもrevertすれば良いので楽です。grepしたり、sed, awkしたりするのも簡単です。とにかく取り回しやすい、の一言に付きます。昔は、LaTexという組版用のマークアップ言語も使っていましたが、プレビューするのに若干手間が掛かり、また、最近は数式は滅多に書きませんので、マークダウン一本です。

理由その２：構造化が楽

文章には構造がありますよね。#で第１レベルの見出し、##で第２レベルの見出し、###で…。#だけで見出しを表現出来ます。また、箇条書きも簡単です。-で書き出すだけです。数字付きの箇条書きなら、1.で書き出すだけ。同じことをWordやHTMLで書こうと思うと、大した手間ではないにせよ、積み重なるとかなりの生産性ダウンです。

理由その３：対応ソフトウェアが増えた

GitHub、GitLab、Backlogと言ったITSとVCSを一体化したサービス・製品では、マークダウンをデフォルトでサポートしています。また、私が普段使っているVS Codeもマークダウンをサポートしていますし、エンハンス出来る拡張機能も沢山出ています。ここで言う対応、と言うのは、マークダウンで書いたものをきちんと解釈してレンダリングしてくれる、という意味です。どれもプレビュー機能を備えているので、書きながらレンダリング結果を確認することが出来ます。それから、pandocというソフトウェアを使えば、マークダウンをWordに出力することも出来ます。これはかなり便利です。編集している間は一番生産性の高いテキストファイルで書き、完成したらWordに出せる、というのは嬉しすぎるとしか言いようがありません。また、plantumlというツールをインストールすると、テキストファイルでUMLも書けちゃいます。私の場合は、plantumlとVSCode拡張を使って、クラス図やシーケンス図、パッケージ図、配置図などを描いています。

Markdown系VSCode拡張

VSCodeは最早なくてはならないエディタになってきました。もうエディタの域を超えています。マークダウンで書くにあたって入れている拡張をご紹介します。

markdownlint

リンターです。リンターってのは、スタイルなどの規約違反を教えてくれる奴のことです。おかしなところは波線で教えてくれます。

Markdown PDF

マークダウンをPDFにエクスポートしてくれますが、最近はあまり使っていません。

Markdown　Preview Enhanced

これは強力です。plantumlのプレビュー画像もこれがないと見られません。プレビュー画面から画像にしたり、HTMLにしたり、PDFにしたりも出来ますし、出力のスタイルも多少は変えられます。

Markddown All in One

これも強力です。特に気に入っているのは、見出しから目次を作ってくれる機能です。一度作ると見出しの更新の度に目次の更新もやってくれます。自動補完機能もついています。箇条書きのときは特に便利です。

Excel to Markdown table

マークダウンは便利なのですが、表を書くのが若干面倒です。この拡張は、クリップボードにコピーされているExcelで書いたセルを、マークダウンの表のフォーマットで貼り付けてくれます。

環境の違う人に渡すとき

VSCode拡張のお陰で仲間内では絶大な便利さを発揮するマークダウンですが、仲間外に渡すときは少し注意が要ります。今のところ一番注意しているのは、plantumlで書いた図を渡すときです。流石にインストールして下さいとは言えないので、ちょっと工夫が要ります。私の場合は、以下のようにしています。

  1. 普通にマークダウンで書く。

  2. エンハンストプレビュー画面から、HTMLへ出力する。

  3. 出力したHTMLに、svg画像が埋め込まれているので、そこだけ切り取ってsvgとして保存する。

  4. マークダウンの図の部分をsvgへのリンクに置き換える。

GitLabには、PlantUMLで書いてもプレビュー出来る機能があるので、相手がGitLabを使っている時はそのまま渡せます。ただ、GitLabのその機能は、デフォルトでは入っていないので、その確認は必要ですね。

今回は、マークダウンについてのあれこれでした。
では。


この記事が気に入ったらサポートをしてみませんか？