はじめに

Qiitaで記事を書くようになると今まで以上にMarkdownでテキストを書く機会が増えてきましたが、
まだMarkdownを十分に理解していないので上手く書けずに苦労しました。

そこで今までQiitaの記事やGitHubのReadme.mdを書くときによく使うものや編集環境の設定などを備忘録としてまとめておきます。

Markdown記法

見出し

#を先頭につけることとその行が大文字表記になります。HTMLタグで言うところのh1相当ですね。
#の数を増やすと順にh2、h3相当になります。
#の後ろに半角スペースを一文字入れないと認識してくれないので注意。

これが、

# 1行目です
## 2行目です
### 3行目です

↓こうなります。

1行目です

2行目です

3行目です

#の数で文字サイズが変わるので覚えやすい&使いやすいですね。Qiitaではこれで見出しを付けて投稿すると自動的に記事右側に内部リンクがはられるのので読みやすい記事を書こうと思うと必須になってきます。

リスト表示

htmlタグで言うところのli相当ですね。-か*か+を先頭につけるとリストとして認識されます。インデントを付けるとネストを深くしたリストが作れます。

これが、

* 外見出し1
+ 外見出し2
    - 中見出し1
        - 内見出し1
        - 内見出し2
    - 中見出し2
* 外見出し3

↓こうなります。

外見出し1
外見出し2
- 中見出し1
  - 内見出し1
  - 内見出し2
- 中見出し2
外見出し3

リンク

外部リンク

外部URL等へのリンクを貼るときに使います。公式のドキュメント等にリンクを貼るとき必須になりますね。
[表示名](リンク先)の形で書きます。[]の中に書いた内容が見出しとして、()の中に書いたURLがクリック時のリンク先として動作します。

これが、

[Google](https://www.google.com)
[Qiita](https://qiita.com/)

↓こうなります。

Google
Qiita

もちろん表示と中身を一致させないと読む人が混乱するので気をつけて。
書いた後に動作確認したほうがいいでしょう。

内部リンク

ページ内の見出しにリンクを貼るときに使います。
[表示名](#リンク先見出し名)の形で書きます。[]の中に書いた内容が見出しとして、(#)の中に書いたURLがクリック時のリンク先として動作します。

これが、

[外部リンク](#外部リンク)
[内部リンク](#内部リンク)

↓こうなります。

外部リンク
 内部リンク

内部リンクを貼るときは()の中に#を付けて見出し文を入力すると同一ページ内の見出しにリンクを貼れます。
#はそれぞれの見出しのサイズに関わらず一つだけです。
あとQiitaでは見出し文字列の英語はすべて小文字に、.は削除しないとリンク先を認識しないのでご注意を。
実際初めて内部リンクを書いたときはこれが分からず小一時間ほど格闘してました。
こちらも書いた後に動作確認しておくことをお勧めします。

訂正線(2020/09/24追記)

入力した文字の上に横線を引いて内容を生成するときに使えます。
訂正線を入れたい文字列の前後を~~で囲むと横線が引かれた状態で表示されます。

これが

~~この文書の内容を更新したいが、更新前のものも比較用に残したいので訂正線を入れます。~~

↓こうなります。

~~この文書の内容を更新したいが、更新前のものも比較用に残したいので訂正線を入れます。~~

VSCodeでの下書き

Qiitaで直接記事を書いてもいいのですが、私は一度VSCodeで書いてからQiitaにコピペする形で書いています。
VSCodeはMarkdownにも対応していて便利な拡張機能が色々とありますし、オンラインでいきなり長文を書くのは編集途中に接続が切れて内容が消えるリスクを避けたいというのもあります。
(あとブラウザ上での作業中に command + w をやってしまって泣いたことがあるので。)

というわけでVSCodeでMarkdownを書くときのコツをまとめていきます。

prettierはMarkdownのフォーマッターには向かない

VSCodeでは鉄板のフォーマッター、prettierはMarkdownにも対応しているのですが日本語環境で、というか英語環境以外で使うと些か使い勝手がよくない。
日本語だけで書くのならまだそこまででもないのですが、英単語も混ぜた文を書いてprettierで整形する場合。

これが、

VSCodeでMarkdownを編集してprettierでフォーマットする

こうなります。

VSCode で Markdown を編集して prettier でフォーマットする

英単語の前後に半角スペースが追加されてしまいます。
コーディング時は可読性をあげようとできるだけスペースを入れたりマメに改行したりしてますが、Readme等では余計なスペースや改行が入れられると書きにくい&読みにくくなってしまいます。
Qiitaで記事を書く以外にもGitHubのReadme.mdを書くときにも毎回prettierの挙動には困らされてきました。
そこでprettier以外のフォーマッターを使用してみます。

prettierをMarkdownで無効化

まずはprettierをMarkdownでは動作しないように設定します。
command + shift + p でコマンドパレットを開いてsetting.jsonを開きます。
Markdownがprettierの編集対象外になるよう設定を追加します。

"prettier.disableLanguages": [
        "markdown",
    ],

保存すればMarkdown(.mdファイル)にprettierは動作しなくなります。
ただこれだけだとMarkdownに対して整形してくれるものがなくなるので別のフォーマッターを追加します。

markdown-formatterのインストール(後日、使用停止)

prettierの代わりになるフォーマッターをインストールします。
軽く探してみたところmarkdown-formatterというVSCode拡張機能がよさそうだったのでこれをインストールします。

markdown-formatter - VisualStudio Marketplace

簡単に使ってみた範疇ではprettierで困らされていた英単語の前後に半角スペースが挟まれる問題は解消されました。保存時の自動実行にも対応しているので、しばらくはこれでやってみたいと思います。

他にもMarkdown向けの拡張機能で良さそうなものもいくつかありました。
今回は試してませんが、折をみて動作を確認していきたいところです。

Markdown All in One - markdown-formatterよりも高機能なフォーマッター(みたい)。
markdownlint - Makdown向けのlinter。

markdownlint(2020/09/14追記)

markdown-formatterもしばらく使っていましたが、これも今ひとつ使い勝手はよくありませんでした。
英単語と日本語の間にスペースが自動的に挿入される問題は一応は解消しましたが、バッククオートを使用したインライン表示を挿入するとその前後にスペースが挿入されてしまいました。

そのため、markdown-formatterの代わりに前に挙げたmarkdownlintを使ってみました。
またmakdownlint等のフォーマッターは文章の校正は行わないので、文書の校正ツールとしてtextlintも試してみました。

markdownlint - Github

markdownlintはmarkdownファイル向けのスタイルチェッカー、linterです。
markdown-formatterよりも細かく設定でき、こちらのほうが使い勝手は良さそうなので使ってみます。

npmパッケージで提供されているのでnpmかyarnでインストール。

$ yarn add markdownlint

またVSCode向けの拡張機能も提供されていて編集、保存時の自動実行に対応してくれるのでこれも導入します。

markdownlint - VisualStudio MarketPlace

markdownlintには40以上のフォーマットルールがあり、それぞれ個別にon/offにすることができます。
setting.jsonで自動実行と共に記述できるので、まとめて書いていきます。

setting.json

{
    ...,
    //実行タイミングの設定。
    "markdownlint.run": "onType",
    "markdownlint.config": {
        "default": true,
        "commands-show-output": false,
        "blanks-around-headers": { "lines_above": 2, "lines_below": 1 },
        "fenced-code-language": false,
        "first-line-h1": false,
        "no-multiple-blanks": { "maximum": 2 },
        "single-h1": false,
        "ul-indent": { "start_indented": true },
        "ul-style": { "style": "sublist" }
    }
}

"derault": trueにすることで、全ルールがデフォルト値で実行されます。
そこ加えて不必要なルールを無効化、または引数をを追加する形で調整してきます。

各ルールはドキュメントを参照してください。
Rules.md - markdownlint

textlint(2020/09/14追記)

markdownlintはあくまでmarkdown向けのフォーマッターであって、文書そのものの校正は行いません。
textlintが文書校正ツールとしてはどうも良さそうなので試してみました。

textlint本体だけでなくtextlintの校正ルールはtextlint-rule-*の形でnpmパッケージとして提供されており、各パッケージを追加することで各ルールを追加できるようになっています。

textlit校正ルール

使用できるルールはここから確認できます。

Collection of textlint rule

いろいろある中から以下のものを使ってみます。

一文で使える"、"の数のチェック。デフォルトでは最大3つ textlint-rule-max-ten
逆接の接続助詞「が」が、同一文中に複数回出現していないか検出 textlint-rule-no-doubled-conjunctive-particle-ga
同じ接続詞で開始されていることを検出 textlint-rule-no-doubled-conjunction
二重否定の検出 textlint-rule-no-double-negative-ja
二重助詞の検出 textlint-rule-no-doubled-joshi
一文の最大の長さ textlint-rule-sentence-length
ら抜き言葉を使用しない textlint-rule-no-dropping-the-ra
文の敬体(ですます調)、常体(である調)の混合をチェック textlint-rule-no-mix-dearu-desumasu
「ポケットエンジン」のような、MacOSXでPDFやFinderからのコピペで発生する濁点のチェック textlint-rule-no-nfd
制御文字の検出 textlint-rule-no-invalid-control-character
リンク切れの検出 textlint-rule-no-dead-link
本文が存在しない見出しの検出 textlint-rule-no-empty-section
日付と曜日が一致しているかどうか検出 textlint-rule-date-weekday-mismatch
リスト項目にピリオドやカンマ、句読点が含まれているか検出 textlint-rule-period-in-list-item
サロゲートペアが含まれているか検出 textlint-rule-no-surrogate-pair
括弧”(){}[]「」”が閉じられているかチェック textlint-rule-no-unmatched-pair

ルールの数が多いので「探すの面倒！」って人にはルールをまとめたプリセットもも用意されているので。そちらを利用するのも手です。

Rule Presets:Japanse - textlintGithub

日本語環境向けのプリセットルール集もあります。

textlint-rule-preset-japanese

textlint、プリセットルール集インストール

両方ともnpmパッケージで提供されているので、npm installまたはyarn addコマンドで追加します。

$ yarn add textlint
$ yarn add textlint-rule-max-ten
$ yarn add textlint-rule-no-doubled-conjunctive-particle-ga
$ yarn add textlint-rule-no-doubled-conjunction
$ yarn add textlint-rule-no-doubled-joshi
$ yarn add textlint-rule-no-double-negative-ja
$ yarn add textlint-rule-sentence-length
$ yarn add textlint-rule-no-dropping-the-ra
$ yarn add textlint-rule-no-mix-dearu-desumasu
$ yarn add textlint-rule-no-nfd
$ yarn add @textlint-rule/textlint-rule-no-invalid-control-character
$ yarn add textlint-rule-no-dead-link
$ yarn add textlint-rule-no-empty-section
$ yarn add textlint-rule-date-weekday-mismatch
$ yarn add textlint-rule-period-in-list-item
$ yarn add textlint-rule-no-surrogate-pair
$ yarn add @textlint-rule/textlint-rule-no-unmatched-pair

数も多いしので一括でインストールしちゃいましょう。

$ yarn add textlint　textlint-rule-max-ten textlint-rule-no-doubled-conjunctive-particle-ga textlint-rule-no-doubled-conjunction textlint-rule-no-doubled-joshi textlint-rule-no-double-negative-ja textlint-rule-sentence-length textlint-rule-no-dropping-the-ra textlint-rule-no-mix-dearu-desumasu textlint-rule-no-nfd @textlint-rule/textlint-rule-no-invalid-control-character textlint-rule-no-dead-link textlint-rule-no-empty-section textlint-rule-date-weekday-mismatch textlint-rule-period-in-list-item textlint-rule-no-surrogate-pair @textlint-rule/textlint-rule-no-unmatched-pair

インストールが完了したら、textlint設定ファイル.textlintrc作成します。
このファイルがないとtextlintの校正ルールをいくらインストールしてもそれらを認識しないので忘れないように。
textlint --initコマンドで作成できます。

$ yarn textlint --init

textlintさえインストールしてあればいつでも作成可能ですが、各ルール追加してから作成するとインストールした各ルールについて項目が追加された状態で作成されるので、設定の変更が容易になります。

.textlintrcファイルでは各項目の有効化/無効化の設定ができるのでインストールしたルールは有効化/無効化するだけでなく、オプションの設定をすることも可能となっています。
またプリセットルールを使用する場合、含まれるルールを個別で調整/無効化することもできます。

詳しくは各ルールのドキュメントを参照してください。

また.textlintrcはtextlint --initコマンドで作成するとJSON形式で作成されますが、拡張子がついてないのでこのままではVSCodeの補完機能が使えないので追加しておきます。
もちろん手動で変更してもokです。

$ mv .textlintrc .textlintrc.json

設定ファイルの作成後、textlintコマンドで校正を実行できます。

$ yarn textlint "対象のファイル"

VSCodeなら拡張機能を導入することでprettier等と同様に、保存時に自動で実行するように設定を追加することができます。

vscode-textlint

インストールしたらsettgin.jsonを編集して設定を追加しておきます。

setting.json

{
    ...
    //保存時の自動修正機能、デフォルトではfalse。trueにしておけば可能な項目は保存時に自動で修復されます。
    "textlint.autoFixOnSave" : true,

    //textlitn実行のタイミング設定、デフォルトではonSave
    "textlint.run" : "onType"
}

これで編集、保存のたびに自動実行してくれます。
他にもいくつかあったけどとりあえず必要なのはこの２つくらいのようなのでこれだけ項目を追加しておきます。

※2020/09/24追記
"textlint.run":"onType"を"textlint.run":"onSave"に変更しました。
というのもtextlintが有効になったプロジェクトをVSCodeで開いているとネットワークが数分と待たずに落ちて、再起動しない限り復旧しないという自体に直面しました。
おそらく"textlint.run":"onType"とtextlint-rule-no-dead-linkが重なったために、頻繁にリンク先確認のためのネットワークアクセスが多発したためかと推察しています。
それがどうやってネットワーク接続不調を引き起こすかまではわかりませんが、vscode-textlintの実行タイミングをonTypeからonSaveに変更して、ネットワークへのアクセス負荷を減らすことで一応は解消しました。
まぁonTypeだとネットワークへのアクセスの問題を抜きにしても、頻繁にmdファイルへのアクセスが発生して端末の負荷増大になっていたであろうことは容易に推測できるのでこれで良かったのかと思ってます。

その他注意事項

Markdownでは2行以上の改行はまとめて1行分しか認識されない。
Qiita編集画面では全角、半角が意外と見分けづらい。
Qiitaでは1回の改行で表示も改行されるが、VSCodeでは2回改行しないと改行と認識されない。

あとがき

Qiitaに記事を書くのは学んだ技術、知識の整理にもなるし備忘録にもなるのでこれからもちょこちょこ書いていきたいところですが、Markdownで書くとなると色々独自の文法が必要になってくるので今後もちょこちょこ更新していきたいところですね。

...とおもったらこちらこちらに色々まとめてありましたね。
とはいっても勉強のためにも自分でも色々模索していきます。

参考&参照した記事

VSCodeでMarkdownの自動フォーマット＆整形ルールを自由に設定 - Qiita
Markdown記法チートシート - Qiita

※2020/09/14追加
ルールプリセットを使ってお手軽にtextlint入門
 VisualStudioCodeでMarkdown編集環境を整える - Qiita

Qiitaで記事を書くときの備忘録

はじめに

Markdown記法

見出し

1行目です

2行目です

3行目です

リスト表示

リンク

外部リンク

内部リンク

訂正線(2020/09/24追記)

VSCodeでの下書き

prettierはMarkdownのフォーマッターには向かない

prettierをMarkdownで無効化

markdown-formatterのインストール(後日、使用停止)

markdownlint(2020/09/14追記)

textlint(2020/09/14追記)

textlit校正ルール

textlint、プリセットルール集インストール

その他注意事項

あとがき

参考&参照した記事