Go to Qiita Advent Calendar 2024 Top
LoginSignup
99
112

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@tomokin966

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

Last updated at Posted at 2019-04-15

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）を選択する。

参考にしたページ
MarkDownで画像コピペ！PDFドキュメントを高速で作成する。 - Qiita

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

Create Link - Chrome ウェブストア

ワンクリで簡単に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個はめんどい

  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

Markdown TOCが正常に動かない

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

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

参考にしたページ
Markdown TOCの改行に"auto"が入ってしまいうまく動かない - 白旗製作所

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

Markdown TOCを導入した状態で、下みたいに書いたら保存した時に勝手に再生成してくれる。

## 目次

<!-- TOC depthFrom:2 -->

<!-- /TOC -->

参考にしたページ
vscodeの AlanWalk/markdown-toc extensionで目次の自動生成すると捗るぞ - Islands in the byte stream

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

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ファイルが開かれるので、以下のコードを追記して保存。


	"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」すらめんどいから個人的にはいい感じ。

setting.json
"[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コードで独自のスニペットを作成する

99
112
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
99
112

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?