Markdown形式で作成した設計書には、下記のような特徴があります。
- 変更をgit管理できる
- html, pdfなどへの変換が簡単
- Wordなどと比べてエディタがとても軽量
- CSSを使って装飾できる
- 検索がやりやすい
- 表は書きにくい
そのため、Wordを使うくらいならMarkdownを使うほうがいいと思いますし、DB設計などの表や関数・参照などを多用したい場合はExcelを使ったほうがいいと思います。
この記事を読めば、目次の追加や、装飾を行った下図のような設計書が作れるようになります。
また、設計書のサンプルはgithubで公開しています。
https://github.com/TomokiIshimine/MarkdownBaseDocument.git
もくじ
使用するエディタ
私はVS Codeを使っています。
非常に軽量で使い勝手もよく、コーディングにも使えるので便利です。
下記の拡張機能をインストールして使いましょう。
Markdown All in One
Markdownを編集する上で便利な機能を複数使えるようになる拡張機能。
VS CodeでMarkdownを編集するなら、入れない理由がないほど優秀です。
Ctrl + Bで太字にしたり、目次を追加することが出来ます。
https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
Markdown PDF
MarkdownをPDFに変換できる拡張機能。
実はPDFだけではなく、HTMLやJPEGなどの画像にも変換できます。
https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf
markdownlint
構文チェックを行っていくれるリンターです。
Markdownの品質を保つことが出来るので、入れておいたほうがいいでしょう。
複数人で設計書の更新をする時にも効果を発揮します。
https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
構文チェックのルールは厳しめのため、場合によっては邪魔になることもあります。
その場合は.markdownlint.jsonファイルを用意して、その中に無視したいルールを記述することによって、任意のルールを無視することが出来ます。
私は、htmlを使いたいため、下記を記述してhtmlタグを使用できるようにしています。
{
"no-inline-html": false
}便利な小技
設計書の見た目や、機能性にはある程度こだわりたいものです。
Markdownはほとんどカスタマイズが出来ないと思っている方も多いのですが、拡張機能やCSSを用いて、思ったよりも見た目などをこだわることが可能です。
後述するテクニックは、基本的に上述した拡張機能をインストールしていることを前提としています。
ヘッダーにセクション番号を付ける
Markdown All in Oneを使えば、ヘッダーにセクション番号を簡単に付けられます。
- Ctrl + Shift + Pを押してコマンドパレットを開く
- 「Markdown All in One : Add/Update section numbers」を選択
目次の作成
Markdown All in Oneをインストールしていれば、簡単に目次を追加できます。
- 目次追加したい場所にカーソルを合わせる
Ctrl + Shift + Pを押してコマンドパレットを開く- 「Markdown All in One : 目次(TOC)を作成」を選択
作成した目次は、PDFに変換したときに、クリックすれば目的のセクションにジャンプするリンク機能も備えています。
また、.vscode/settings.jsonに下記の設定を追加することで、目次を作成するヘッダーのレベルを設定できます。
デフォルトだとH1の目次も作成されるため、下記のようにH2から目次を作成するように設定することをお勧めします。
{
"markdown.extension.toc.levels": "2..6"
}特に言及されていませんが、上記の設定は前述したセクション番号の割り振りにも対応しています。
デフォルトだとH1から採番されてしまいますが、上記を設定することによってH2から採番されます。
PDFへの出力
Markdownの生ファイルを設計書として共有するわけにもいきません。
Markdown PDFをインストールして、PDFやhtmlに出力して共有しましょう。
テキストの適当なところを右クリックし、「Markdown PDF: Export(pdf)」 を選択すれば簡単にPDF出力できます。
PDFに変換した場合の改ページ
PDFに変換すると、見出しのすぐ下など、予期せぬところで改ページされてしまうことがあります。
読みにくさの原因にもなるので、任意の場所で改ページさせましょう。
下記のhtmlを追加することで改ページできます。
<div style="page-break-before:always"></div>画像のサイズ調整
Markdownではで画像を追加できますが、表示される画像の大きさを調整することはできません。
サイズを調整したい場合は、htmlで画像を追加しましょう。
画像を追加したい場所に、下記を記述することでサイズを調整した画像を挿入できます。
<img src="画像リンク" height="300">PDFに変換した場合もちゃんと適応されています。
CSSによる装飾
デフォルトだとシンプルすぎて、ヘッダーや表が見にくいと言われることがあります。
そんなときはCSSを使って装飾しましょう。
Markdownのファイルと同じディレクトリにcssファイルを配置し、Markdownの先頭に下記を記述すれば、CSSをプレビューやPDF変換時の見た目に適用できます。
<link href="markdown.css" rel="stylesheet"></link>私は下記のcssをよく使っています。
主にヘッダーや表の見た目を弄っています。
表に関するTips
左寄せ・センタリング・右寄せ
下記のように、ヘッダー部の下に:-、:-:、-:を記述することによって、それぞれ左寄せ・センタリング・右寄せができます。
-(ダッシュ)の数はいくつでもかまいません。
| 左寄せ | センタリング | 右寄せ |
| :------- | :----------: | -------: |
| hogehoge | hogehoge | hogehoge |
| hoge | hoge | hoge |セル内で改行
<br>タグを用いて改行できる。
| 左寄せ | センタリング | 右寄せ |
| :------- | :----------: | -----------: |
| hogehoge | hogehoge | hoge<br>hoge |
| hoge | hoge | hoge |表のフォーマット
Markdown All in OneをインストールしていればAlt + Shift + Fで表のフォーマットができる。
|左寄せ|センタリング|右寄せ|
|:-|:-:|-:|
|hogehoge|hogehoge|hoge<br>hoge|
|hoge|hoge|hoge|| 左寄せ | センタリング | 右寄せ |
| :------- | :----------: | -----------: |
| hogehoge | hogehoge | hoge<br>hoge |
| hoge | hoge | hoge |まとめ
Markdownで設計書をかけるようになると、設計書の作成速度や保守性が格段に上がります。
設計書のベースさえ用意しておけばすぐに作成を始めることが出来るので、自分が使いやすい設定でベースを一つ作っておくことをお勧めします。
おまけ
HackMDという、Markdownテキストを共同編集できるWebアプリがあります。
設計書を共同編集するだけでなく、議事録作成やリモート会議などにも便利なので、お試しください。
他にも機能があるので、詳しくは公式を参照。