Markdownで文書を書くためにやったこと一覧

# Markdownで文書を書くためにやったこと一覧

## 目次


<!-- TOC depthFrom:2 -->

- [Markdownって何？](#markdownって何)
- [Markdownを使うのにやったこと](#markdownを使うのにやったこと)
    - [1. Markdownエディターの選定](#1-markdownエディターの選定)
    - [2. Markdown関連の拡張機能をいろいろ入れる](#2-markdown関連の拡張機能をいろいろ入れる)
    - [3. Chromeに拡張機能「Create Link」を入れる](#3-chromeに拡張機能create-linkを入れる)
    - [4. いい感じのCSSを適用させる](#4-いい感じのcssを適用させる)
- [その他 細かいこと](#その他-細かいこと)
    - [改行するのに空白2個はめんどい](#改行するのに空白2個はめんどい)
    - [PDF化する時の改ページ](#pdf化する時の改ページ)
    - [Markdown TOCが正常に動かない](#markdown-tocが正常に動かない)
    - [目次をわざわざつけるのめんどい](#目次をわざわざつけるのめんどい)
    - [目次をつけるやつをコピペするのもめんどい](#目次をつけるやつをコピペするのもめんどい)
    - [入力補完の候補を出すための「Ctrl + Space」すらめんどい](#入力補完の候補を出すためのctrl--spaceすらめんどい)

<!-- /TOC -->

<div style="page-break-before:always"></div>

## Markdownって何？
>Markdown（マークダウン）は、文書を記述するための軽量マークアップ言語のひとつである。本来はプレーンテキスト形式で手軽に書いた文書からHTMLを生成するために開発されたものである。
[Markdown \- Wikipedia](https://ja.wikipedia.org/wiki/Markdown) より引用

手軽にきれいに書ける文書フォーマットみたいなやつ。

開くのに専用のソフトは要らず、ブラウザとかでも一応見れるし、プレビューソフトで見ればキレイに表示できる。

文字はもちろん、引用、リンク、画像、表などなどをいい感じに表示できる。

## Markdownを使うのにやったこと

### 1. Markdownエディターの選定

いろんなエディターがあるけど、シンプルで使いやすくて、汎用性の高い「VSCode」を選択。

[Visual Studio Code \- Code Editing\. Redefined](https://code.visualstudio.com/)

リッチなテキストエディターながら、軽量で軽快に動作する。

<div style="page-break-before:always"></div>

### 2. Markdown関連の拡張機能をいろいろ入れる

[Paste Image](https://marketplace.visualstudio.com/itemdetails?itemName=mushan.vscode-paste-image)
Ctrl + Alt + V で画像をMarkdownにコピペできるようにするやつ。

[Markdown PDF](https://marketplace.visualstudio.com/itemdetails?itemName=yzane.markdown-pdf)
MarkDownをPDFに変換するやつ。
1. 右クリックから Markdown PDF:Export (pdf) を選択します。
2. 作成されたPDFファイルをダブルクリックして表示します。


[vscode\-pdf](https://marketplace.visualstudio.com/itemdetails?itemName=tomoki1207.pdf)
VSCodeでPDFの表示出来るようにするやつ。

[markdown\-index](https://marketplace.visualstudio.com/itemdetails?itemName=legendmohe.markdown-index)
見出しの番号付けしてくれるやつ。
1. コマンドパレットを開いて（Ctrl + P）
2. addindexと入力してEnterを押す。

[Markdown TOC](https://marketplace.visualstudio.com/itemdetails?itemName=AlanWalk.markdown-toc)
目次を見出しで作成してくれるやつ。
1. 目次を挿入したい場所にカーソルを合わせます。
2. 右クリックから Markdown:TOC Insert/Update （Ctrl + M T）を選択する。

>参考にしたページ
[MarkDownで画像コピペ！PDFドキュメントを高速で作成する。 \- Qiita](https://qiita.com/keita69sawada/items/1fad093f5871a6fb9a62)

<div style="page-break-before:always"></div>

### 3. Chromeに拡張機能「Create Link」を入れる

[Create Link \- Chrome ウェブストア](https://chrome.google.com/webstore/detail/create-link/gcmghdmnkfdbncmnmlkkglmnnhagajbm?hl=ja)

ワンクリで簡単にMarkdown向けのリンクが作れる。

作りたいページのどっかで右クリック→Create Link→markdown でクリップボードにコピーしてくれる。

### 4. いい感じのCSSを適用させる

---
2019/08/09 追記

わざわざCSS作らなくてもこの拡張機能ぶち込めば良い感じなるみたい。
これでよくね？

[Markdown Preview Github Styling \- Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles)

でも、PDFにもスタイルを適応したい人は以下の手順が必要。

2020/12/10 追記

↑のMarkdown Preview Github Stylingを内包した拡張機能を見つけた。

[Github Markdown Preview \- Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview)

これを入れればMarkdown関連がGithubと一緒になるらしい。
絵文字も使えるし、yaml方式での付加情報にも対応できるみたい。

---

GitHubのmarkdown用CSSパクってる人がいたので、その人のアイディアを~~パク~~拝借した。

>https://raw.githubusercontent.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css
↑からコピペもしくはダウンロード
適当なエディタで1を開き、.markdown-でfind、''(空文字)でreplace
現場からは以上です。(｀･ω･´)ゞ

この手順通りやると”GitHubみたいないい感じのCSS”ができる。

出来たCSSをワークスペースの`settings.json`にこんな感じで指定してあげる。

```
"markdown.styles": ["cssのパス"]
```

※パスを書くときは `"C:\\Users\\<ユーザー名>\\.vscode\\md_preview.css"` こんな感じに`\`を`\\`ってエスケープしてあげる

[Markdown PDF](https://marketplace.visualstudio.com/itemdetails?itemName=yzane.markdown-pdf)でPDF吐く時に使うCSSにも同じのをぶち込む。

`C:\Users\<ユーザー名>\.vscode\extensions\yzane.markdown-pdf-x.x.x\styles`

↑のディレクトリの`markdown.css`をさっき作った”GitHubみたいないい感じのCSS”で置き換える。


VSCodeのMarkdownプレビューは背景色がテーマに左右されるので、GitHub丸パクリだとダークテーマの時にクソ見にくいから背景色を指定してあげる。

```
body {
  background-color: white;
  color: #24292e;
}
```
↑のコードを適当な位置にぶち込む。

>参考にしたページ
[githubのmarkdown\-cssをぶっこ抜く方法 \- Qiita](https://qiita.com/__mick/items/c80fab6c185a41882880)
[Visual Studio Code の CSS を見やすくカスタマイズしてみました \- Qiita](https://qiita.com/08thse/items/205eea7ed85188ae38bf)

<div style="page-break-before:always"></div>

## その他 細かいこと

### 改行するのに空白2個はめんどい

1. ファイル → 基本設定 → 設定 で「markdown」って検索
2. 「Markdown > Preview: Breaks」のチェックボックスにチェックを入れる

```
"markdown.preview.breaks": true
```
を`settings.json`に追記してもOK

### PDF化する時の改ページ
このままだとPDF化した時に改ページ位置が指定できないから見にくい。

改ページしたいところに以下のコードを入れることで、強制的に改ページ出来る。

```
<div style="page-break-before:always"></div>
```

>参考にしたページ
[VScodeのMarkdownからPDF変換時に改ページを挿入 \- Qiita](https://qiita.com/0xmks/items/4fec4116bb42120f5180)

### Markdown TOCが正常に動かない

アップデートでVSCodeの改行文字のデフォルトが「auto」になったせい。

1. ファイル → 基本設定 → 設定 で「eol」って検索
2. 「Fiels: Eol」を`\r\n`に変更する

>参考にしたページ
[Markdown TOCの改行に"auto"が入ってしまいうまく動かない \- 白旗製作所](http://dededemio.blog.fc2.com/blog-entry-69.html)

### 目次をわざわざつけるのめんどい

[Markdown TOC](https://marketplace.visualstudio.com/itemdetails?itemName=AlanWalk.markdown-toc)を導入した状態で、下みたいに書いたら保存した時に勝手に再生成してくれる。

```
## 目次

<!-- TOC depthFrom:2 -->

<!-- /TOC -->
```

>参考にしたページ
[vscodeの AlanWalk/markdown\-toc extensionで目次の自動生成すると捗るぞ \- Islands in the byte stream](https://gfx.hatenablog.com/entry/2016/11/16/114051)

### 目次をつけるやつをコピペするのもめんどい

1つ上で紹介した「自動で目次をつけてくれるやつ」をコピペするのすらめんどいので、ユーザースニペットに登録して予測変換で出るようにした。

ファイル → 基本設定 → ユーザースニペット を選択。

「スニペットファイルの選択もしくはスニペットの作成」って出てきたらスニペットを作りたい言語を選ぶ。

今回は「markdown」を選択。

```markdown.json
{
	// Place your snippets for markdown here. Each snippet is defined under a snippet name and has a prefix, body and 
	// description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the 
	// same ids are connected.
	// Example:
	// "Print to console": {
	// 	"prefix": "log",
	// 	"body": [
	// 		"console.log('$1');",
	// 		"$2"
	// 	],
	// 	"description": "Log output to console"
	// }
}
```
↑こんな感じのjsonファイルが開かれるので、以下のコードを追記して保存。

```json-doc

	"Insert TOC": {
		"prefix": "toc",
		"description": "Insert TOC",
		"body": [
			"## 目次",
			"",
			"<!-- TOC depthFrom:2 -->",
			"<!-- /TOC -->"
		]
	}
```

これで「toc」ってタイプして「Ctrl + Space」を押すと候補として出てくる。

↓が記述内容の解説

```json-doc

// スニペットの名称
"Insert TOC": {

    // スニペットの呼び出し名
		"prefix": "toc",

    // スニペットの説明文
		"description": "Insert TOC"

    // スニペットの中身
    // 複数行の場合は [ ] で囲んで " " , 改行 " " , って感じで書けばいける
    // スニペット入力後のカーソル位置は $1で指定可能
    // $1 $2 $3... って連番で指定すると、Tabを押すたびに$1 $2 $3... って感じで移動できる
		"body": [
			"## 目次",
			"",
			"<!-- TOC depthFrom:2 -->",
			"<!-- /TOC -->"
		]
	}
```

ちなみにjsonにはコメントを書く方法がないらしいので、VSCodeの設定用jsonは厳密にはjson-docっぽい？


<details><summary>筆者が定義しているスニペット一覧</summary><div>

```json-doc
{
	"Insert TOC": {
		"prefix": "toc",
		"description": "目次を挿入する",
		"body": [
			"## 目次",
			"",
			"<!-- TOC depthFrom:2 -->",
			"<!-- /TOC -->"
		]
	},
	"Insert Date": {
		"prefix": "date",
		"description": "日付を挿入する yyyy/mm/dd aaa",
		"body": "$CURRENT_YEAR/$CURRENT_MONTH/$CURRENT_DATE ${CURRENT_DAY_NAME_SHORT}"
	},
	"Page Break Down": {
		"prefix": "page",
		"description": "pdf用の改行コードを挿入する",
		"body": "<div style=\"page-break-before:always\"></div>"
	},
	"Insert Table Tags": {
		"prefix": "tabel",
		"description": "table用のタグを挿入する",
		"body": [
			"|a  |b  |c  |",
			"|---|---|---|",
			"|1  |2  |3  |",
			"|4  |5  |6  |"
		]
	},
	"Insert Details Tags": {
		"prefix": "details",
		"description": "折りたたみタグを挿入する",
		"body": [
			"<details><summary>${1:折りたたみ名}</summary><div>",
			"\t${2:内容}",
			"</div></details>"
		]
	},
	"Insert Anker Link": {
		"prefix": "anker",
		"description": "アンカーリンクを挿入する",
		"body": "[${1:リンクテキスト}](#${2:リンク先の見出し名})"
	}
}
```
</div></details>

>参考にしたページ
[Visual Studio Code ソースコードはスニペットと「Ctrl \+ space」で書いちゃいなよ](https://mseeeen.msen.jp/vscode-snippet/)

### 入力補完の候補を出すための「Ctrl + Space」すらめんどい

設定で常に入力補完候補が表示されるようにする。

邪魔なときもあるけど、「Ctrl + Space」すらめんどいから個人的にはいい感じ。

```setting.json
"[markdown]":  {
    "editor.quickSuggestions": true
  }
```

>参考にしたページ
[VSCodeでマークダウンを書くためのチート \- Qiita](https://qiita.com/nkgr/items/57a3278879313c32f557)

### スニペットで使える変数集

VSCodeのスニペットはなんかいろいろ変数が使えるっぽい。

今日の日付や曜日なんかを変数で指定できるので、日付を入れる時とかに便利。

以下の変数が使用できます。

クリップボード、ディレクトリ関連

* $TM_SELECTED_TEXT 現在選択されているテキストまたは空の文字列
* $TM_CURRENT_LINE 現在の行の内容
* $TM_CURRENT_WORD カーソル下の単語の内容または空の文字列
* $TM_LINE_INDEX 行番号(0始まり)
* $TM_LINE_NUMBER 行番号(1始まり)
* $TM_FILENAME 現在の文書のファイル名
* $TM_FILENAME_BASE 現在のドキュメントの拡張子を除いたファイル名
* $TM_DIRECTORY 現在の文書のディレクトリ
* $TM_FILEPATH 現在の文書のフルファイルパス
* $CLIPBOARD クリップボードの内容

日付関連

* $CURRENT_YEAR 年
* $CURRENT_YEAR_SHORT 年の下2桁
* $CURRENT_MONTH 2桁の月（例 '02'）
* $CURRENT_MONTH_NAME 月のフルネーム（例 '7月'）
* $CURRENT_MONTH_NAME_SHORT 月の短縮形（例 'Jul'）
  ↑日本語だと'7 月'みたいな感じで間にスペースが入るから基本使わない
* $CURRENT_DATE 日
* $CURRENT_DAY_NAME 曜日（例 '月曜日'）
* $CURRENT_DAY_NAME_SHORT 曜日の短縮形（例 '月'）
* $CURRENT_HOUR 時
* $CURRENT_MINUTE 分
* $CURRENT_SECOND 秒

コメント関連（言語によってコメント表記は自動で切り替わる）

* $BLOCK_COMMENT_START コメントスタート
  出力例：PHP `/*` HTML`<!--`
* $BLOCK_COMMENT_END コメントエンド
  出力例：PHP `*/` HTML`-->`
* $LINE_COMMENT 行コメント
  出力例：PHP `//` HTML`<!-- -->`

曜日関連とか月関連は設定言語に左右される。
日本語設定で使っている人なら基本的には日本語表記になるはず。

「YYYY/MM/DD AAA」(例 2019/04/01 月)をスニペットに登録する場合

```
$CURRENT_YEAR/$CURRENT_MONTH/$CURRENT_DATE ${CURRENT_DAY_NAME_SHORT}
```

>参考にしたページ
[Visual Studioコードで独自のスニペットを作成する](https://code.visualstudio.com/docs/editor/userdefinedsnippets)