始めに、Markdownは「軽量で書きやすい」ことから多くの人が文書作成やブログ、技術ドキュメントに使っているテキストフォーマットです。
しかし、初心者がつまずきやすいポイントや、普段つぎると思いもよらないエラーがあります。
この記事では、よくあるMarkdownの問題をピックアップし、それぞれの原因と対処法をわかりやすくまとめました。すでに一度は「Markdownの書式が崩れた」「リンクがつかない」などという悩みを抱えている方は、ぜひ最後まで読んで対策を把握してみてください。
1️⃣ Markdownの基礎が不安定になる主な理由
1-1. 改行を入れたのに次の段落がつながってしまう
Markdownでは、段落を分ける際に改行だけではなく、改行の前に空行を入れる必要があります。
これは段落1です。
これは段落2です。
これを行わずに 改行 だけを入力した場合、エディタがHTMLに変換すると <p> タグが1つだけで、結局は「段落1」と「段落2」が1つの段落として扱われてしまいます。
1-2. 画像やリンクの書き方を間違えている
正しい書式は次のように記述します。
-
画像
 -
リンク
[リンクテキスト](https://example.com "オプションタイトル")
小さなスペルミスや角括弧・丸括弧を逆にしてしまっているケースが多いです。
特に画像の先頭に付く ! を忘れると、単なるリンクとして処理されます。
2️⃣ エディタ・レンダラーによる違いに注意
2-1. マルチプレイヤーなMarkdownエディタの挙動
-
Visual Studio Code の拡張機能
Markdown Preview Enhanced
Markdown構文全般をサポートし、LaTeXやMermaid図の描画も可能ですが、#を数個置くだけでは見出しが H1 でしか表示されないことがあります。
VSCode内の設定でmarkdown.preview.highlightを「true」にすると、見出しレベルが正しくハイライトされます。 -
Typora
デフォルトでリアルタイムプレビューを提供しますが、--(ダッシュの連続) を見出しとみなす機能が無効化されている場合、-- Headingが正常に表示されません。
設定 > Markdown のチェックボックス「Use###for heading」 をオンにしてください。
2-2. GitHub Flavored Markdown (GFM) の特殊仕様
GitHub上では、以下の構文が動作しません。
| テキスト | GFMで動作しない | 代替方法 |
|---|---|---|
| 列挙リストの太字 | ** で囲むと強調されない |
<strong> タグを使う |
| タイムスタンプ | HH:MM:SS 形式で自動リンク |
Markdownリンクに変換する ([1:30](#) のように) |
3️⃣ よくあるスタイリングミスとその対策
3-1. リストのインデントが不統一
番号付きリストと箇条書きの混在時にインデントが不揃いだと、下位リストが正しくネストされません。
1. 先頭アイテム
- サブアイテム
* 更にサブサブアイテム
上記は「先頭」と「サブ」の混在で意図せぬ見出しになるケースが多いです。
対策は 2スペースのインデント を統一し、箇条書きはハイフン (-) のみを使用しましょう。
3-2. 行頭にスペースを入れたらコードブロックに。
行頭に 4つスペース 以上を入れると自動的にコードブロック扱いになります。
int main() {
return 0;
}
意図せずにコードブロック化したくない場合は、行頭に > を付けて引用符のように書くか、バッククォートで区切りましょう。
3-3. 改行したいときに \n\n だけではダメ
Markdownでは「単一改行」は自動で <br> タグに変換されません。
改行を挿入したい場合は 3つ以上の空白 で改行するとレンダリング側が改行として処理します。
行1の最後にスペース３つを入れます。
行2
あるいは <br> タグを明示的に入れる方法もあります。
4️⃣ テーブルで起こるよくあるエラー
4-1. 列数の不一致
テーブルを作る際にヘッダー行とデータ行で列数が違うと、全体が崩れます。
| 列1 | 列2 |
|---|---|
| 値1 | 値2 | 値3 <-- ここで列数が増える
必ず同じ列数（ヘッダーとデータ行）に揃えてください。
4-2. パイプ記号 | が欠ける
| 列1 列2 |
|---|---|
ヘッダーでは | を忘れないで。
欠けると一行目だけがヘッダーとして解釈され、残りの行が連続したテキストとして表示されます。
5️⃣ コードブロックでよく見られるミス
5-1. 言語指定を間違える
```python
print("Hello")
上の例は正しくPythonとしてハイライトされます。
もし `py` と書いてしまうとハイライトされない場合があります。
対応言語は大文字小文字を区別しないこともあるので、仕様を確認してください。
### 5-2. インラインコードでバッククォートが複数ある場合
文字自体にバッククォートが含まれると、周囲のバッククォートで囲む際に `>` で回避します。
```markdown
`printf("`Hello`")` ← ここは期待通りにレンダリングされない
対策は バッククォートの数を増やす（例: printf("`Hello`")）や、HTMLエンティティ (`) を使う方法です。
6️⃣ 見出しに関する注意点
6-1. 空白を入れずに連続記号を使うとハッシュが無視される
##Heading のようにハッシュと文字の間に空白がないと、Markdownパーサーは見出しとして扱いません。
常に # （ハッシュとスペース）を忘れずに書くべきです。
6-2. 記号が多すぎると不揃いになる
見出しを強調したい場合、### より多く入れると見た目がおかしくなる可能性があります。
スタイルは下記程度に抑えましょう。
| レベル | 文字 |
|---|---|
| H1 | # |
| H2 | ## |
| H3 | ### |
| H4 | #### |
| H5 | ##### |
| H6 | ###### |
7️⃣ テキスト全体の品質を保つコツ
-
エディタのプレビュー機能を活用
書いたMarkdownをその場で確認できるエディタ（Typora、Mark Text、MacDown など）を使うと、見直しが楽になります。 -
リファクタリングを頻繁に行う
文章が長くなるほど、一度に全体を読むのは困難です。見出しごとに区切ったり、テスト投稿でプレビューを見る習慣を付けましょう。 -
一貫した書式設定
画像、リンク、コードブロックなど、同じ書式規則を統一することで、長期的にメンテナンスしやすくなります。 -
コメントアウトを残す
文章の構造を示す<!-- ここは注釈 -->を入れておくと、後で見直す際に役立ちます。 -
プラグイン・拡張機能の確認
使っているエディタに組み込まれている Markdown プラグインは、標準仕様とは微妙に違う挙動をすることがあります。公式ドキュメントで挙動を確認しましょう。
8️⃣ まとめ
- 改行・空行を正しく使い、段落を分けることが基本。
- 画像・リンクは必ず正しい構文を守る。
- エディタ毎のレンダラー違いを理解し、必要に応じて設定変更。
- リスト・テーブル・コードブロックはインデント・列数・バッククォートに注意。
- 見出しは必ずハッシュと空白で書く。
- 一貫性とレビューを意識し、品質を保つ。
Markdownはシンプルながら細部に注意が必要なフォーマットです。
この記事で紹介した共通の落とし穴を事前にチェックすれば、初心者でも「文書が崩れた」「リンクが動かない」という悩みを減らすことができます。
ぜひ、実際に自分のブログやREADMEを書いて試してみてください。手を伸ばすたびに「ほんの少しだけ修正したら見栄えが劇的に変わる」という発見がありますよ。 Happy Markdown!
コメント