markdownで避けるべきこと

markdown を使うことで装飾された文章を書くことができますが、書く上で避けるべき markdown の記法や気をつけねばならないことがあったりします。 ここではそのような避けるべきパターンを紹介していきます。

1. 密集したコメント

<!-- ここはコメントアウトされる --><!-- これはされない -->

改行を挟まずに繰り返しコメントアウトが続くと 2 つ目以降のコメントが適切にコメントアウトされないことがあります。

コメントの間はしっかり改行するようにしましょう。

2. 改行コード

この文章を途中で改行したいからって<br/>を挟むのは良くない

markdown では改行は無視されます。 改行を使いたい場合は<br/>を使ったりやスペース 2 つを行末に挿入することで強制的に改行をすることができますが、 このサイトのような場合、改行をすることで見た目を整えることは環境によっては逆に見にくくなってしまう可能性があるため、 むやみに改行を使用する事は推奨されません。

改行ではなく空行を挟み段落を変えることで読みやすい文章を目指しましょう。

3. h1 見出し

# このような h1 見出しは用いるべきではない

docusaurus を用いたこのサイトのような場所でのみ当てはまる事なのですが、 h1 見出しは記事自体の見出しになるため、記事の最初の一回のみ使用されるべきです。

また h1 見出しは記事の目次にインデックスされないので文中の見出しとして用いるべきではありません。

---
title: ここに見出しを書く
---

本文は見出しではなく内容から始める

見出しは h1 見出しとして書くのではなく、 このようにヘッダーに記載することを推奨しています。

4. mdx でのコメント

<!-- このコメント記法は本来mdxの仕様にはない -->

mdx では上記のようなコメントアウトは許されておらず、以下のようなコメントアウトを用いるべきです。

{/* mdxではこのコメント記法を使いましょう */}

しかし md ではこの方法は使えないので mdx と md では引き続き<!-- -->のコメントアウトを使い分けましょう。