Markdown でマニュアルの作成
Markdown でマニュアルの作成
Markdown 楽だよねってことで、Markdown で業務マニュアル作成することにしたので、その手順のまとめ
VSCode の Markdown 用の拡張をいくつかインストールしておく
- Markdown All in One、目次の作成と章番号の追加など
- Markdown Preview Enhanced、Markdown のプレビュー
- Markdownlint、書式の確認
- Markdown PDF、PDFへの出力
目次
1. マニュアルの記述
Markdownを使ってマニュアルを作成していく。
mdファイルの上で右クリックして、「Markdown Preview Enhanced Open Preview to the Side」でプレビュー画面が右ペインに表示される。
mdファイルを編集すれば自動的に更新されていくのでWYSIWYGで編集できる。
# を使って章番号を設定しておくと VSCode の左にあるアウトラインから章に移動することができる。便利
編集内容に問題があれば Markdownlint が下線で警告してくれるので、クリックすると修正内容を提案してくれる。
画像などは必要なところに直接コピペすると、 という感じで貼り付けてくれる。
便利だけど理想的には images ディレクトリを作成しておき、そこに保存をして、
な感じで修正したほうがいいかもしれない。
2. 章番号と目次の作成
VSCode のコマンドパレットを開いて(Windows:Ctrl+Shift+p、Mac:Shift+Command+p) Markdown All In One のコマンドで章番号、目次の作成できる。
章番号の追加、更新は
Markdown All in One: Add/Update section numbers
章番号、目次に含めたくない場合は
<!-- omit in toc -->
を見出し行の前にいれておく。
見出しを追加更新した場合には再度Add/Update section numbersを実行して章番号を更新する。
目次は
Markdown All in One: Create Table of Contents
で目次を作成してくれる。
作成した目次はリンクになっているのでそこから対象へ移動することができる。
3. PDF化
作成したマニュアルをPDF化したい場合には、mdファイルを右クリックして「Markdown PDF: export (PDF)」でPDFファイルにすることができる。
4. 余談
もともとは Word で作成するつもりだったのだが、ざっくり見出しを作った時点で7章、100項目以上になりそうで、サブ文章に分けることとか、アウトラインで編集するなど考えたのだが差分も取りにくいし画像のいちとかレイアウトを考えるのも大変ということで Markdown で書くことにした。
Wordのアウトラインモードで画像や表の扱いがらくになるとか、履歴差分がわかりやすくなる方法などがあればもうちょっとWordも検討対象になったのだが。
