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

# はじめに
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](https://www.google.com)
[Qiita](https://qiita.com/)

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

### 内部リンク

ページ内の見出しにリンクを貼るときに使います。
`[表示名](#リンク先見出し名)`の形で書きます。`[]`の中に書いた内容が見出しとして、`(#)`の中に書いた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](https://marketplace.visualstudio.com/items?itemName=mervin.markdown-formatter) 

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

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

* [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) - markdown-formatterよりも高機能なフォーマッター(みたい)。
* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) - Makdown向けのlinter。


## markdownlint(2020/09/14追記)

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

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

[markdownlint - Github](https://github.com/DavidAnson/markdownlint)

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

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

```
$ yarn add markdownlint
```

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

[markdownlint - VisualStudio MarketPlace](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)

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

```JavaScript: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](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)


## textlint(2020/09/14追記)

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

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


### textlit校正ルール

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

  - [Collection of textlint rule](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule)

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

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


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

  - [Rule Presets:Japanse - textlintGithub](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule#rule-preset-list)


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

  - [textlint-rule-preset-japanese](https://github.com/textlint-ja/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](https://marketplace.visualstudio.com/items?itemName=taichi.vscode-textlint)

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

```JavaScript: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で書くとなると色々独自の文法が必要になってくるので今後もちょこちょこ更新していきたいところですね。

...とおもったらこちら[こちら](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)に色々まとめてありましたね。
とはいっても勉強のためにも自分でも色々模索していきます。

# 参考&参照した記事

[VSCodeでMarkdownの自動フォーマット＆整形ルールを自由に設定 - Qiita](https://qiita.com/the_red/items/e121cbb659c52a60bca6#comments)
[Markdown記法 チートシート - Qiita](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)


※2020/09/14追加
[ルールプリセットを使ってお手軽にtextlint入門](https://efcl.info/2015/12/30/textlint-preset/)
[VisualStudioCodeでMarkdown編集環境を整える - Qiita](https://qiita.com/kumapo0313/items/a59df3d74a7eaaaf3137)