📖

Markdown 活用法

2021/02/22に公開

📌 はじめに

個人的にドキュメントやメモを書くときのテキストフォーマットに，テキストファイル，Html，Textile，TeX, ReStructuredText とか試してきて，今は Markdown 形式に落ち着いています．メモやプレゼンの資料を作成するときなど，ほとんどが Markdown で書ける環境になりました．記述するときのフォーマットは Markdown ですが，使用するソフトウェアは用途によって異なります．この記事では，用途に応じた Markdown ファイルの活用方法について紹介したいと思います．なお，私の主なPC環境は Windows ですので，Windowsで動作確認しているものを紹介しますが，ほとんどがマルチプラットフォームで動作すると思います．

📌 Visual Studio Code

Visual Studio Code

Markdown ファイルを書くときには VSCode を使っています．デフォルトの Markdown Preview は使っておらず，「Markdown Preview Enhanced」パッケージを使っています．他にも Markdown 形式で記述するときに便利なパッケージがありますので，重宝しています．

📌 Typora

Typora

こちらもエディタではありますが，エディタとしての機能はイマイチで，主にビューアとして使っています．とはいえ，簡単な文書を書く程度ならこれで十分かもしれません．また，PDF のエクスポートが比較的良好なので，Markdown 形式を PDF に変換したいときなどに便利です．epub 形式などもサポートしています．スタイルシートで見た目のカスタマイズ出来るのもいいところです．

📌 Marp

Marp

Markdown 形式で記述できるプレゼン資料作成ソフトです．かなり捗るので，作成するプレゼンのスライド枚数がいつの間にかすごい量になってたりします．個人的に PowerPoint などで特に不便を感じているのが数式の記述なのですが，Mathjax のおかげで TeX 形式で書けるので大変便利です．スタイルシートで見た目のカスタマイズ出来るのもいいところです．

Marp は新しく Marp Next という形で開発が続けられています．Marpはデスクトップアプリでスタンドアローンで動作するツールでしたが，Marp Nextではモジュールに分割され，フレームワークやCLIから操作するツールに変わりました．といっても，VSCodeでMarpを扱う拡張機能が提供されているので，それを使えば以前とほとんど使い勝手は変わりません．最初のMarpよりかは若干機能が無くなっている部分がありますが，とても便利です．

Marp for VS Code

📌 Notion

Notion

最近人気が出ている共有ツールです．Markdown形式で書くこともできるし，コマンドによる記述もできて，かなり柔軟なレイアウトを構築できます．また，Markdown形式やPDF形式のエクスポート，動画など他のサービスとの連携，簡単にページを公開することができるなど様々です．私も最初使い始めたときは数式が対応されていなかったので，切り替えることができなかったのですが，それも後からインラインも含めて対応されたので，今はメインツールとして使っています．無料でストレージ使い放題になったのも高評価でしたね．アップロードの上限が少ないので，それのために有料プランを使っています．例えば，以下のような記事を書いて公開しています．

📌 Mkdocs, Gitbook, Doxygen, Mdbook, Docute

Markdownを使ってドキュメントを作成するツールです．色々ありますが，Webなら Mkdocs, PDF にしたいなら gitbook，HTMLヘルプ形式にしたいなら Doxygen といった感じでしょうか．それぞれ解説記事を投稿していますので参考にしてみてください．

他にも，最近人気のプログラミング言語である Rust で使われている mdbook というのが有力かなと思います．Rust製のGitbookといった感じです．ただ，PDF作成は標準で対応していなかったと思います．

mdbook

他には Docute というのもお手軽で便利です．Mkdocs や mdbook などもそうなのですが，ページ構成を記述しなければいけないので面倒です．docute では README.md ファイルやフォルダ名に対応した .md ファイルを自動検索してくれるので簡単ですし，とてもシンプルなので場合によってはこれで十分なこともあります．

Docute

📌 Boostnote

Boostnote

Markdown 形式で記述できるメモソフトです．
ファイル構成もシンプルで同期しやすく，複数PCでも快適です．
メモソフトとして，個人的に必須な数式の記述も出来るし，とても使いやすいです．
現在は使っていないので，どういう状況なのか把握できていないのですが，当時スマホに対応していなかったり，検索が使いづらかったことがあって別のに切り替えました．

📌 他の人に渡すときは

たとえ相手がエンジニアでも Markdown ファイルを直接渡すことはあまりしていません．PDF にするか，HTML 形式に変換して渡しています．HTML 形式の場合は VSCodeの Markdown Preview Enhanced を使ってエクスポートしています．体裁を調整する場合は，エクスポートした HTML ファイルを直接修正してスタイルシートをいじっています．PDF や印刷する場合は，エクスポートした HTML ファイルを Chrome で開いて，印刷したり PDF で保存しています．また，Typora でエクスポートすれば様々な形式で出力することが出来ます．

📌 Markdeep

Markdeep

Markdeep は Markdown 形式で書かれたファイルを論文のような体裁で表示してくれる Javascript です．使い方は簡単で，Markdown ファイルをそのまま拡張子 .html にして保存し，特定のコードを入れるだけで綺麗な文書を作成出来ます．公式では PDF に変換するときは wkhtmltopdf を使う方法が紹介されていましたが，どうも上手くいかなかったので，Chrome から PDF にしています．ここでは，私が使っている設定などを解説します．

多言語をサポートしています．ファイルのヘッダにメタ属性を埋め込みます．

<meta lang="ja" charset="utf-8">

日本語のフォント（NotoSans）を使うために，以下の指定をします．

<link rel="stylesheet" href="https://fonts.googleapis.com/earlyaccess/notosansjp.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:600,800">

フォントの指定など体裁を少しカスタマイズします．font-size は印刷時などで調整します．

body { font-size: 10pt; font-family: "Noto Sans JP"; max-width: 1200px; },
.md code { font-family: Consolas; }
.md pre.backtick {
  border-top: 1px solid #CCC;
  border-bottom: 1px solid #CCC;
  padding: 5px 0 5px 20px;
  margin: 0 0 0 0;
  background: #FCFCFC;
  page-break-inside: avoid;
}

数式に自動で番号が割り振られてしまうと困るときがあるので，以下で回避できます．

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
    equationNumbers: {
      autoNumber: false
    }
  }
});
</script>

これを指定しても align で指定しているものは番号が割り振られるので，そのときは align* を使います．

これらを設定をファイルの先頭に，そしてファイルの末尾に以下を入れます．

<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:,monospace}</style><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js?"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

画像のサイズを全体的に調整したい場合は，次のようにします．

<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:,monospace}</style><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js?"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
<style>
  .md img { width: 30%; };
};
</style>

また，デフォルトでは目次が自動で作られて表示されますが，これを無効にしたい場合は次のようにします．

<script>window.markdeepOptions = {tocStyle:'none'}</script><!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:,monospace}</style><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js?"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

スタイルシートを使ってマルチカラム形式で表示することが出来ます．次のような感じで表示されます．

マルチカラム形式にするためには，スタイルシートに以下を追加します．

.mcol2 {
columns:2;-webkit-columns:2;-moz-columns:2;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}
.mcol3 {
columns:3;-webkit-columns:3;-moz-columns:3;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}
.mcol4 {
columns:4;-webkit-columns:4;-moz-columns:4;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}

たとえば，次のように指定します．

<div class="mcol2">
  ２カラムで表示されます
</div>

<div class="mcol3">
  ３カラムで表示されます
</div>

<div class="mcol4">
  ４カラムで表示されます
</div>

自動で整列されるので，スタイルシートを使って適当な余白を入れたり，+++++++ でページ送りが出来ます．

Markdeep は見出しに自動的に番号を割り振ってくれます．細かいフォーマットを指定できますので，詳細は公式サイトを参照してください．たとえば，この番号を非表示にしたいとき，スタイルシートに次を追加します．

.md h3:before, .md h4:before { content:none }

最後に個人的に使っている基本テンプレートです．まずファイルの先頭には

<meta lang="ja" charset="utf-8">
<link rel="stylesheet" href="https://fonts.googleapis.com/earlyaccess/notosansjp.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:600,800">
<style>
body { font-family: "Noto Sans JP"; max-width: 1200px; },
.md code { font-family: Consolas; }
.md pre.backtick {
  border-top: 1px solid #CCC;
  border-bottom: 1px solid #CCC;
  padding: 5px 0 5px 20px;
  margin: 0 0 0 0;
  background: #FCFCFC;
  page-break-inside: avoid;
}
.mcol2 {
columns:2;-webkit-columns:2;-moz-columns:2;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}
.mcol3 {
columns:3;-webkit-columns:3;-moz-columns:3;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}
.mcol4 {
columns:4;-webkit-columns:4;-moz-columns:4;column-gap:3em;-webkit-column-gap:3em;-moz-column-gap:3em;
}
</style>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: {
    equationNumbers: {
      autoNumber: false
    }
  }
});
</script>

そして，ファイルの末尾には

<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:,monospace}</style><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js?"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

📌 さいごに

実際に書いてまとめてみると，あんまり使いこなしていない感じがしてきましたが…
本記事が参考になれば幸いです．