Markdown + VScodeで設計書や仕様書を作成す

自社で新規開発を担当させていただくこととなりました。
そこで仕様書や設計書などのドキュメントをgitで管理したいということもあり、
ExcelやWordではなくMarkdownで作成したい。

だけど実は一度もMarkdownを書いたことがない。。
（※ということはQiitaも初投稿・・・！）

という状況なので、実際にドキュメントを書き始めるまでの手順の備忘録です。

今回使用するエディタは**VScode**です。
## Markdownチートシート系
以下の記事を参考させていただいてます。

[ブログでよく使うMarkdownの書き方を忘れたときにみるもの。](https://qiita.com/kamorits/items/6f342da395ad57468ae3)

[Qiita マークダウン記法 一覧表・チートシート](https://final.hateblo.jp/entry/2016/09/19/120820)

[Markdown記法 チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)

## Markdownファイルの作成・編集

VSCodeでプレビューの表示をしながら作成・編集します。

コマンド↓
>コマンドパレット：［Markdown: プレビューを横に表示］（Markdown: Open Preview to the side）
キーボード：［Ctrl］＋［K］→［V］（Win／Linux）、［Command］＋［K］→［V］（macOS） 

または、エディタ右上の[プレビューを横に表示]を押下します。

参考：[VS CodeでMarkdownをプレビューするには？](https://www.atmarkit.co.jp/ait/articles/1804/20/news030.html)

# Markdown拡張機能の導入
以下記事を参考にさせていただきました。
[VisualStudioCodeでMarkdownを書く際に入れておきたい便利な拡張機能5選](https://qiita.com/sola-msr/items/cfe448db958da3d08863)  
## Markdown All in One

### Markdown形式のファイルを記述する際に使えるショートカットキーが増える

使えるキーはあまり多くない気がする・・・

例：

| キー               | 結果          |
|------------------|-------------|
| ctrl + b         | 太字      |
| ctrl + i         | 斜体        |
| ctrl + shift + ] | ヘッディングレベル上げ |
| ctrl + shift + [ | ヘッディングレベル下げ |

### mdファイルを開いたときに自動でサイドバーにプレビューを表示する

設定を開いて[自動でプレビューを横に表示する]にチェックをいれます。すごく便利！

![markdownimage.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/660804/c5a0f3d4-33a9-bc44-7b60-d9f60db9a9cd.png)

### 目次を生成する(TOCの作成）

見出しの一覧を作成してから［F1］を押し以下コマンドを入力します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/660804/0399f323-ba46-664f-3097-50d26f3f497b.png)

すると目次ができます。ちゃんと目次から各項目にリンクしてる！

文章量の多いドキュメントを書くときに使えそう

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/660804/eb01b01e-7419-04fa-f5bc-5cafa919b4e3.png)

### 作成したmdファイルを自動でHTMLファイルに出力する

mdファイルと同じディレクトリに生成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/660804/4e79a691-c403-7526-bda0-e6884830a51d.png)

今回は作成したドキュメントをHTMLではなくPDF変換するので使わないかもしれない。



インストール：[Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)

## Markdown PDF

### mdファイルをPDFやHTMLに変換して書き出してくれる
出力したいファイルの上で右クリックメニューから以下のコマンドを実行します。

**PDF出力**

```
Markdown PDF: Export (pdf)
```
**HTML出力**

```
Markdown PDF: Export (html)
```

他にも、PNG、JPEGファイルにも変換可能。

### 出力先path変更

setting.jsonを開き

```
"markdown-pdf.outputDirectory": "出力先path"
```
を追記します。

インストール：[Markdown PDF](https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf)

##Excel to Markdown table

Excelで作成したテーブルをコピーして`Shift+Alt+V`で貼り付けるとmd形式でテーブルを記述してくれます。

テーブルデータを扱うときにすごく便利そう

インストール：[Excel to Markdown table](https://marketplace.visualstudio.com/items?itemName=csholmq.excel-to-markdown-table)




# ドキュメント作成手順
### ディレクトリ構成
```
root/
   ├pdf/ 
   │   ├要件定義/
   │   │     └ 要件定義書.pdf
   │   ├基本設計
   │   │     ├ 画面遷移図.pdf
   │   │     ├ 画面一覧.pdf
   │   │     ├ テーブル定義書.pdf
   │   │     └ 機能一覧.pdf
   │     etc..
   │
   └md/
      ├要件定義/
      │     └ 要件定義書.md
      ├基本設計
      │     ├ 画面遷移図.md
      │     ├ 画面一覧.md
      │     ├ テーブル定義書.md
      │     └ 機能一覧.md
　　    etc..
 
```
要件定義書であれば、
`md/要件定義/`に`要求定義書.md`を作成し、Markdown PDFの

```
Markdown PDF: Export (html)
```
を実行すると、`pdf/要件定義/`に`要求定義書.pdf`が作成されます。

※出力先は以下に設定してあります

```
"markdown-pdf.outputDirectory": "../../pdf/要件定義"
```
作成するドキュメントの工程が変わるたびにpathを変えるのは少し面倒かも・・・仕方ない？

# 画像読み込みについて
imgタグで画像を読み込む際に、画像URLを生成する必要があります。

[GitHubでREADME.mdに画像を使用したい](https://qiita.com/lowg/items/06dd096e7ed1acce4b1e)

上記記事を参考にリポジトリに画像をアップロードし、生成されたURLを指定します。

```
<img src="生成された画像URL" alt="画像" width=50%>
```