Zenn の Markdown 記法：見やすい記事を書くための基本と応用

By /

Zenn の Markdown 記法：見やすい記事を書くための基本と応用

Zenn は、技術に関する情報を共有し、コミュニティを育むための素晴らしいプラットフォームです。そこで発信する記事は、Markdown という軽量マークアップ言語で記述します。Markdown は、シンプルで書きやすく、可読性が高いのが特徴です。

本記事では、Zenn で見やすい記事を書くために必要な Markdown 記法の基本と応用を、具体的な例を交えながら解説します。初心者の方から、さらに表現力を高めたい方まで、役立つ情報が満載です。

1. Markdown の基本：見出し、段落、リスト

まずは、Markdown の基本となる見出し、段落、リストの書き方を見ていきましょう。これらをマスターするだけでも、記事の構成が格段に分かりやすくなります。

1.1. 見出し

見出しは、記事の構造を明確にするために不可欠です。# の数で見出しのレベルを表現します。

“`markdown

見出し 1

見出し 2

見出し 3

見出し 4

見出し 5
見出し 6

“`

上記のように記述すると、以下のように表示されます。

見出し 1

見出し 2

見出し 3

見出し 4

見出し 5
見出し 6

見出しは、記事の主題を伝え、読者が興味のある部分にすぐにアクセスできるようにするために重要です。適切なレベルの見出しを使い分け、論理的な構造を心がけましょう。

1.2. 段落

段落は、文章を意味のあるまとまりに区切るために使用します。Markdown では、空行を挟むことで段落を区切ります。

“`markdown
これは最初の段落です。文章を改行しても、同じ段落として扱われます。

これは2番目の段落です。このように空行を挟むことで、新しい段落が開始されます。
“`

上記のように記述すると、以下のように表示されます。

これは最初の段落です。文章を改行しても、同じ段落として扱われます。

これは2番目の段落です。このように空行を挟むことで、新しい段落が開始されます。

段落を適切に区切ることで、文章が読みやすくなり、内容が理解しやすくなります。

1.3. リスト

リストは、情報を整理して提示するのに役立ちます。順序付きリストと順序なしリストの2種類があります。

1.3.1. 順序なしリスト

順序なしリストは、項目の順序が重要でない場合に利用します。*、-、+ のいずれかの記号を使用します。

markdown
* 項目 1
* 項目 2
* 項目 3

上記のように記述すると、以下のように表示されます。

  • 項目 1
  • 項目 2
  • 項目 3
1.3.2. 順序付きリスト

順序付きリストは、項目の順序が重要な場合に利用します。数字とピリオドを使用します。

markdown
1. 項目 1
2. 項目 2
3. 項目 3

上記のように記述すると、以下のように表示されます。

  1. 項目 1
  2. 項目 2
  3. 項目 3

リストは、箇条書きで情報を整理するのに適しています。複雑な情報を分かりやすく伝えるために、積極的に活用しましょう。リストの中にさらにリストをネストすることも可能です。

markdown
1. 項目 1
* サブ項目 1
* サブ項目 2
2. 項目 2

上記のように記述すると、以下のように表示されます。

  1. 項目 1
    • サブ項目 1
    • サブ項目 2
  2. 項目 2

2. テキストの装飾：強調、リンク、画像

次に、テキストを装飾するための記法を見ていきましょう。強調、リンク、画像を使うことで、記事の見栄えが向上し、読者の理解を助けることができます。

2.1. 強調

テキストを強調するには、* または _ を使用します。

  • 太字: **テキスト** または __テキスト__
  • 斜体: *テキスト* または _テキスト_
  • 太字 斜体: ***テキスト*** または ___テキスト___

上記のように記述すると、以下のように表示されます。

  • 太字: **テキスト** または __テキスト__
  • 斜体: *テキスト* または _テキスト_
  • 太字 斜体: ***テキスト*** または ___テキスト___

強調を効果的に使うことで、読者の注意を引きつけ、重要な情報を伝えることができます。ただし、過剰な強調は逆効果になるため、注意が必要です。

2.2. リンク

リンクを挿入するには、[リンクテキスト](URL) の形式を使用します。

markdown
[Zenn の公式サイト](https://zenn.dev/)

上記のように記述すると、以下のように表示されます。

Zenn の公式サイト

リンクテキストは、リンク先のページの内容を簡潔に伝えるようにしましょう。また、title属性を使って、リンクの説明を追加することもできます。

markdown
[Zenn の公式サイト](https://zenn.dev/ "Zenn は技術情報共有プラットフォームです")

上記のように記述すると、リンクにマウスオーバーした際にツールチップが表示されます。

2.3. 画像

画像を挿入するには、![代替テキスト](画像URL) の形式を使用します。

markdown
![Zenn のロゴ](https://zenn.dev/images/logo-square.png)

上記のように記述すると、以下のように表示されます。

Zenn のロゴ

代替テキストは、画像が表示されない場合に表示されるテキストです。SEO対策としても重要なので、必ず記述しましょう。画像のURLは、ローカルファイルパスまたはインターネット上のURLを指定できます。

3. コードの表示：インラインコード、コードブロック

技術記事では、コードの表示が不可欠です。Markdown では、インラインコードとコードブロックの2つの方法でコードを表示できます。

3.1. インラインコード

インラインコードは、短いコード片を文章中に埋め込む際に使用します。`（バッククォート）でコードを囲みます。

markdown
`console.log("Hello, world!");`

上記のように記述すると、以下のように表示されます。

console.log("Hello, world!");

3.2. コードブロック

コードブロックは、複数行のコードをまとめて表示する際に使用します。```（バッククォート3つ）でコードを囲みます。言語を指定することも可能です。

markdownjavascript
console.log(“Hello, world!”);

function greet(name) {
console.log(“Hello, ” + name + “!”);
}

greet(“Zenn”);
“`
““

上記のように記述すると、以下のように表示されます。

“`javascript
console.log(“Hello, world!”);

function greet(name) {
console.log(“Hello, ” + name + “!”);
}

greet(“Zenn”);
“`

言語を指定することで、シンタックスハイライトが適用され、コードが読みやすくなります。Zenn でサポートされている言語は、JavaScript, Python, Java, C++, C#, Go, Ruby, PHP, Swift, Kotlin, TypeScript, Rust, Dart, Scala, Bash, SQL など多岐にわたります。

4. テーブル（表）

データを整理して表示するのに便利なテーブルも、Markdown で記述できます。

markdown
| ヘッダー 1 | ヘッダー 2 | ヘッダー 3 |
|---|---|---|
| データ 1-1 | データ 1-2 | データ 1-3 |
| データ 2-1 | データ 2-2 | データ 2-3 |

上記のように記述すると、以下のように表示されます。

ヘッダー 1 ヘッダー 2 ヘッダー 3
データ 1-1 データ 1-2 データ 1-3
データ 2-1 データ 2-2 データ 2-3

テーブルの各列の配置は、ヘッダー行の下の区切り線で制御します。

  • 左寄せ: |:---|
  • 中央寄せ: |:---:|
  • 右寄せ: |---:|

markdown
| 左寄せ | 中央寄せ | 右寄せ |
|:---|:---:|---:|
| データ 1 | データ 2 | データ 3 |

上記のように記述すると、以下のように表示されます。

左寄せ 中央寄せ 右寄せ
データ 1 データ 2 データ 3

5. 引用

他の文献やウェブサイトからの引用を記述するには、> を使用します。

“`markdown

これは引用です。
複数行にわたる引用も可能です。
“`

上記のように記述すると、以下のように表示されます。

これは引用です。
複数行にわたる引用も可能です。

引用元を明記することで、読者は情報の出所を確認でき、記事の信頼性が向上します。

6. 水平線

セクションを区切るために、水平線を使用することができます。---、***、___ のいずれかの記号を3つ以上並べて記述します。

“`markdown

“`

上記のように記述すると、以下のように表示されます。

水平線は、視覚的に区切りを明確にする効果があります。

7. Zenn 独自の記法

Zenn では、Markdown の標準記法に加えて、独自の記法がいくつか提供されています。

7.1. アコーディオン

アコーディオンは、クリックすることでコンテンツの表示・非表示を切り替えられる機能です。長い文章や補足情報を隠しておきたい場合に便利です。

markdown
:::details クリックして詳細を表示
ここに詳細な内容を記述します。
:::

上記のように記述すると、以下のように表示されます。

:::details クリックして詳細を表示
ここに詳細な内容を記述します。
:::

7.2. メッセージ

記事内で特定のメッセージを目立たせたい場合に、メッセージ記法を使用します。

“`markdown
:::message
これはメッセージです。
:::

:::message alert
これは警告メッセージです。
:::

:::message info
これは情報メッセージです。
:::

:::message success
これは成功メッセージです。
:::

:::message error
これはエラーメッセージです。
:::
“`

上記のように記述すると、以下のように表示されます。

:::message
これはメッセージです。
:::

:::message alert
これは警告メッセージです。
:::

:::message info
これは情報メッセージです。
:::

:::message success
これは成功メッセージです。
:::

:::message error
これはエラーメッセージです。
:::

7.3. コメント

記事中にコメントを記述したい場合に、コメント記法を使用します。コメントは、記事の表示には影響しません。

“`markdown

“`

コメントは、自分用のメモや、他の編集者への指示などを記述するのに便利です。

8. その他の便利な記法

上記以外にも、Markdown には様々な便利な記法があります。

8.1. エスケープ

Markdown の記号をそのまま表示したい場合は、\（バックスラッシュ）でエスケープします。

markdown
\* これは強調ではありません \*

上記のように記述すると、以下のように表示されます。

* これは強調ではありません *

8.2. 特殊文字

特殊文字（©, ®, ™ など）は、HTMLエンティティで記述します。

markdown
© ® ™

上記のように記述すると、以下のように表示されます。

© ® ™

9. 見やすい記事を書くためのヒント

Markdown 記法をマスターするだけでなく、以下の点に注意することで、さらに見やすい記事を書くことができます。

  • 簡潔な文章: 長文を避け、簡潔で分かりやすい文章を心がけましょう。
  • 適切な改行: 段落内でも、意味のまとまりで改行を入れると読みやすくなります。
  • 空白行の活用: 適度に空白行を入れることで、視覚的な区切りを明確にしましょう。
  • 校正・校閲: 誤字脱字や文法ミスがないか、必ず確認しましょう。
  • 読者目線: 読者がどのような情報を求めているのかを考え、記事の構成や内容を検討しましょう。

10. まとめ

本記事では、Zenn で見やすい記事を書くための Markdown 記法の基本と応用について解説しました。見出し、段落、リスト、テキストの装飾、コードの表示、テーブル、引用、水平線、Zenn 独自の記法など、様々な記法をマスターすることで、より表現豊かで分かりやすい記事を作成することができます。

Markdown はシンプルで強力なツールです。ぜひ本記事を参考に、Zenn で素晴らしい技術記事を発信してください。そして、活発なコミュニティを一緒に盛り上げていきましょう。

上記が、Zenn の Markdown 記法について、見やすい記事を書くための基本から応用までを詳細に説明した約5000字の記事です。ご希望に沿えているでしょうか？

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール