Markdownで文書を書くためにやったこと一覧
目次
Markdownって何？
Markdown（マークダウン）は、文書を記述するための軽量マークアップ言語のひとつである。本来はプレーンテキスト形式で手軽に書いた文書からHTMLを生成するために開発されたものである。
Markdown - Wikipedia より引用
手軽にきれいに書ける文書フォーマットみたいなやつ。
開くのに専用のソフトは要らず、ブラウザとかでも一応見れるし、プレビューソフトで見ればキレイに表示できる。
文字はもちろん、引用、リンク、画像、表などなどをいい感じに表示できる。
Markdownを使うのにやったこと
1. Markdownエディターの選定
いろんなエディターがあるけど、シンプルで使いやすくて、汎用性の高い「VSCode」を選択。
Visual Studio Code - Code Editing. Redefined
リッチなテキストエディターながら、軽量で軽快に動作する。
2. Markdown関連の拡張機能をいろいろ入れる
Paste Image
Ctrl + Alt + V で画像をMarkdownにコピペできるようにするやつ。
Markdown PDF
MarkDownをPDFに変換するやつ。
1. 右クリックから Markdown PDF:Export (pdf) を選択します。
2. 作成されたPDFファイルをダブルクリックして表示します。
vscode-pdf
VSCodeでPDFの表示出来るようにするやつ。
markdown-index
見出しの番号付けしてくれるやつ。
1. コマンドパレットを開いて（Ctrl + P）
2. addindexと入力してEnterを押す。
Markdown TOC
目次を見出しで作成してくれるやつ。
1. 目次を挿入したい場所にカーソルを合わせます。
2. 右クリックから Markdown:TOC Insert/Update （Ctrl + M T）を選択する。
3. Chromeに拡張機能「Create Link」を入れる
ワンクリで簡単にMarkdown向けのリンクが作れる。
作りたいページのどっかで右クリック→Create Link→markdown でクリップボードにコピーしてくれる。
4. いい感じのCSSを適用させる
2019/08/09 追記
わざわざCSS作らなくてもこの拡張機能ぶち込めば良い感じなるみたい。
これでよくね？
Markdown Preview Github Styling - Visual Studio Marketplace
でも、PDFにもスタイルを適応したい人は以下の手順が必要。
2020/12/10 追記
↑のMarkdown Preview Github Stylingを内包した拡張機能を見つけた。
Github Markdown Preview - Visual Studio Marketplace
これを入れれば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で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
Visual Studio Code の CSS を見やすくカスタマイズしてみました - Qiita
その他 細かいこと
改行するのに空白2個はめんどい
- ファイル → 基本設定 → 設定 で「markdown」って検索
- 「Markdown > Preview: Breaks」のチェックボックスにチェックを入れる
"markdown.preview.breaks": true
をsettings.jsonに追記してもOK
PDF化する時の改ページ
このままだとPDF化した時に改ページ位置が指定できないから見にくい。
改ページしたいところに以下のコードを入れることで、強制的に改ページ出来る。
<div style="page-break-before:always"></div>
Markdown TOCが正常に動かない
アップデートでVSCodeの改行文字のデフォルトが「auto」になったせい。
- ファイル → 基本設定 → 設定 で「eol」って検索
- 「Fiels: Eol」を
\r\nに変更する
目次をわざわざつけるのめんどい
Markdown TOCを導入した状態で、下みたいに書いたら保存した時に勝手に再生成してくれる。
## 目次
<!-- TOC depthFrom:2 -->
<!-- /TOC -->
参考にしたページ
vscodeの AlanWalk/markdown-toc extensionで目次の自動生成すると捗るぞ - Islands in the byte stream
目次をつけるやつをコピペするのもめんどい
1つ上で紹介した「自動で目次をつけてくれるやつ」をコピペするのすらめんどいので、ユーザースニペットに登録して予測変換で出るようにした。
ファイル → 基本設定 → ユーザースニペット を選択。
「スニペットファイルの選択もしくはスニペットの作成」って出てきたらスニペットを作りたい言語を選ぶ。
今回は「markdown」を選択。
{
// 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ファイルが開かれるので、以下のコードを追記して保存。
"Insert TOC": {
"prefix": "toc",
"description": "Insert TOC",
"body": [
"## 目次",
"",
"<!-- TOC depthFrom:2 -->",
"<!-- /TOC -->"
]
}
これで「toc」ってタイプして「Ctrl + Space」を押すと候補として出てくる。
↓が記述内容の解説
// スニペットの名称
"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っぽい？
筆者が定義しているスニペット一覧
{
"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:リンク先の見出し名})"
}
}
参考にしたページ
Visual Studio Code ソースコードはスニペットと「Ctrl + space」で書いちゃいなよ
入力補完の候補を出すための「Ctrl + Space」すらめんどい
設定で常に入力補完候補が表示されるようにする。
邪魔なときもあるけど、「Ctrl + Space」すらめんどいから個人的にはいい感じ。
"[markdown]": {
"editor.quickSuggestions": true
}
参考にしたページ
VSCodeでマークダウンを書くためのチート - Qiita
スニペットで使える変数集
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コードで独自のスニペットを作成する