マーカダウンのコードブロック - チートシートと使用例

ここでは、Markdownにおけるコードブロックのオプションについてレビューしています。

Markdownコードブロック

Markdownコードブロックは、Markdownドキュメント内でコードやプレフォーマットテキストを表示する方法であり、フォーマットを保持し、必要に応じて構文ハイライトを有効にできます。Markdownにおけるコードフォーマットの主なタイプは2つあり、インラインコードとコードブロックです。

Markdownコードブロックのタイプ

主な違い

• インラインコードは単一のバックティック(`)を使用し、文の中の短いコードに適しています。
• インデントコードブロックは各行の先頭に4つのスペースまたはタブを使用します。構文ハイライトはサポートされておらず、現代的なMarkdownではあまり見られません。
• フェンスコードブロックはトリプルバックティック(```)またはチルダ(~~~)を使用してコードの前後を囲みます。これは特にGitHubなどのプラットフォームで推奨される方法であり、以下の理由からです：
  • 読みやすく、書きやすい。
  • 開始バックティックの後にプログラミング言語を指定して構文ハイライトを有効にできる。
  • フォーマットを保持し、複数行のコードをサポートする。

構文ハイライト付きフェンスコードブロックの例:

以下のMarkdownフォーマットテキストがある場合:

```python
def hello():
    print("Hello, world!")
```

レンダリングされたテキストは以下のようになります:

def hello():
    print("Hello, world!")

Markdownコードブロックのベストプラクティス

• フェンスコードブロック（トリプルバックティック）を使用して複数行のコードを表示し、プラットフォーム間での互換性と明確さを確保してください。
• 開始バックティックの後にプログラミング言語を指定して構文ハイライトを有効にします（例: ``````python）。
• インラインコードを使用して、文の中の短いスニペットやコマンドを表示してください。
• インデントコードブロックは、レガシーコンパチビリティが必要な場合を除き、構文ハイライトをサポートしておらず、読みにくいため避けてください。
• フェンスコードブロックの前後に空白行を配置して、生のMarkdownでの読みやすさを向上させます。

特殊な機能

• 一部のプラットフォームでは、diffなどの追加の言語識別子がサポートされており、コード変更を表示する際に追加または削除された行をハイライト表示できます。
• コードブロック内でバックティックを表示するには、ブロックをより多くのバックティックで囲む（例: 4つのバックティックで3つのバックティックを表示）必要があります。

OutTake

フェンスコードブロックに言語識別子を使用して、読みやすさと構文ハイライトの両方で最適な結果を得てください。インラインコードは短いスニペットに使用し、インデントブロックはコンパチビリティが必要な場合にのみ使用してください。

Diff構文ハイライト

Markdownコードブロックでdiff構文ハイライトを効果的に使用するには、以下の手順に従ってください：

• フェンスコードブロックを使用し、トリプルバックティック（````）でブロックの開始と終了を指定します。
• 開始バックティックの直後に**diffを言語識別子として指定**します。これにより、Gitコミットメッセージやプルリクエストで見られるような差分の構文ハイライトが有効になります。

例:

- old line that will be removed
+ new line that will be added
 unchanged line

• -で始まる行は削除としてハイライト表示されます（通常は赤色）。
• +で始まる行は追加としてハイライト表示されます（通常は緑色）。
• 接頭辞がない行は特別なハイライトはされません。

ベストプラクティス:

• ドキュメント、コードレビュー、または技術ブログでコード変更、修正、または提案を明確に伝えるためにこの形式を使用してください。
• ブロックの前後に空白行を配置して、生のMarkdownでの読みやすさを向上させます。
• diffハイライトは、行の先頭の文字に基づいて全体の行を色分けするだけで、行内での変更はハイライトしません。

ヒント: この方法はGitHub、GitLab、多くのMarkdownレンダラーで広くサポートされており、視覚的にコード変更を共有するための信頼性の高い選択肢です。

サポートされている言語

Markdownコードブロックは、構文ハイライトのために多くの言語をサポートしていますが、サポートされている言語の正確なリストは使用しているレンダラーやプラットフォームに依存します。Markdown自体はサポートされている言語を定義しておらず、単に言語識別子をレンダリングエンジンに渡し、適切な構文ハイライトを適用します。 Markdownコードフェンス自体は公式にサポートされているプログラミング言語の固定リストを定義していません。サポートされている言語のリストは、使用しているMarkdownレンダラーまたはプラットフォーム（GitHub、GitLab、VS Code、Typora、Quartoなど）に依存します。

主要なプラットフォーム（GitHub、VS Code、Bitbucket、Docusaurus、ReadMeなど）で一般的にサポートされている言語には以下があります：

• Web & スクリプト: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• プログラミング: python (py), java, c, c++, c#, php, ruby, go, rust, scala, swift, kotlin, objective-c
• データ & クエリ: sql, r, matlab
• マーキュア & 設定: markdown, ini, toml, dockerfile, makefile
• 特殊: diff, mermaid, geojson, topojson, stl（GitHubでの図やデータ可視化に使用）
• その他: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme、など多数

言語を指定する方法: 開始トリプルバックティックの直後に言語名を使用します:

```python
def hello():
    print("Hello, world!")
```

以下は、MOST Markdownレンダラーで広くサポートされている言語です:

注意: 実際の識別子は変化する可能性があります（例: js vs. javascript）。ほとんどのレンダラーは言語名に対して大文字小文字を区別しません。

サポートされている言語のフルリストを確認する方法:

• GitHub: Linguistを使用してハイライト表示しており、数百の言語をサポートしています。
• VS Code & 一部のウェブレンダラー: highlight.jsまたはPygmentsを使用しています—詳細なリストはドキュメントをご覧ください。
• Bitbucket: CodeMirrorモードとPygmentsリクサーを参照しています。

重要なポイント:

• ほとんどのプラットフォームは、主要なプログラミング、スクリプト、マーキュア言語をサポートしています。
• 一部のプラットフォームは、図やデータ形式（mermaid、geojsonなど）もサポートしています。
• 言語識別子は通常大文字小文字を区別しませんが、互換性を高めるために小文字を使用してください。
• サポートされていない言語識別子を使用した場合、コードブロックはプレーンテキストとしてレンダリングされます。

Markdownコードブロック内でファイル名を指定する

Markdownコードブロック内でファイル名を指定するには、いくつかの方法がありますが、方法はプラットフォームやレンダラーに依存します：

1. コードブロックラベル内のファイル名（メタ構文）

一部のMarkdownエンジン（特定の静的サイトジェネレータ、ドキュメンテーションツール、ブログプラットフォームなど）は、言語の後にコロンで区切ってファイル名を追加するメタ構文をサポートしています：

```js:app.js
console.log("Hello, world!");
```

これにより、レンダラーによってコードブロックの上または横にファイル名（例: app.js）が表示されます。 ただし、このウェブサイトのHugoレンダラーではこの機能はサポートされていません：

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

注意: すべてのプラットフォームでサポートされているわけではありません（例: GitHub風のMarkdownではこの機能は現在サポートされていません）。

2. コードブロックの上にファイル名の見出しまたはインラインコードを使用する

GitHub、Stack Overflow、ほとんどのMarkdownレンダラーで普遍的な互換性を確保するには、コードブロックの上に見出しまたは太字のインラインコードを使用してファイル名を配置します：

**`app.js`**

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

または:

#### `app.js`

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

これにより、ファイル名をコードブロックと視覚的に関連付けることができ、どこでも動作します。

3. コードブロック内でコメントとしてファイル名を含める

また、コードブロック内にコメントとしてファイル名を含めることもできます：

```
// app.js
console.log("Hello, world!");
```

これは、コードをコピーするときにファイル名が表示されるようにするのに特に役立ちます。

まとめとベストプラクティス

コードブロックの上に見出しまたは太字のインラインコードを使用して最大限の互換性を確保し、さまざまなプラットフォームで共有する際にはコード内にコメントとしてファイル名を追加することを検討してください。

有用なリンク

• Markdownチートシート - 最も役に立つ構造とコマンド
• Hugoチートシート
• Bashチートシート - 最も役に立つBashコマンド
• LaTeXチートシート
• Hugoで最も人気のあるテーマ
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks