Markdown 代码块 - 快速参考及使用示例

在这里，我正在回顾 Markdown 中的代码块选项。

Markdown 代码块

Markdown 代码块 是在 Markdown 文档中显示代码或预格式化文本的一种方式，保留格式并可选地启用语法高亮。Markdown 中有两种主要的代码格式：内联代码 和 代码块。

Markdown 代码块的类型

关键区别

• 内联代码 使用单个反引号（`）用于句子中的短代码。
• 缩进代码块 使用每行开头的 4 个空格或一个制表符。它们不支持语法高亮，且在现代 Markdown 中使用较少。
• 栅栏代码块 使用三重反引号（```）或波浪线（~~~）在代码前后。这是首选方法，特别是在 GitHub 等平台上，因为：
  • 它们更易于阅读和编写。
  • 你可以在打开反引号后立即指定编程语言以实现语法高亮。
  • 它们保留格式并支持多行代码。

带语法高亮的栅栏代码块示例：

当我们有如下格式化的 Markdown 文本时：

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

渲染后的文本将如下所示：

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

使用 Markdown 代码块的最佳实践

• 使用栅栏代码块（三重反引号）来显示多行代码，以确保跨平台的清晰度和兼容性。
• 在打开反引号后指定语言 以实现语法高亮（例如，``````python）。
• 使用内联代码 来显示文本中的短代码片段或命令。
• 避免使用缩进代码块，除非出于兼容性需要，因为它们不支持语法高亮且可读性较差。
• 在栅栏代码块前后放置一个空行，以提高原始 Markdown 中的可读性。

特殊功能

• 一些平台支持额外的语言标识符，例如 diff 用于显示代码更改，这可以在代码审查中突出显示添加或删除的行。
• 要在代码块中显示反引号，请用更多反引号包裹代码块（例如，使用四个反引号来显示三个反引号）。

要点

使用 栅栏代码块 并指定语言标识符以获得最佳的可读性和语法高亮。将 内联代码 保留用于短代码片段，并避免使用缩进块，除非出于兼容性需要。

差异语法高亮

要 在 Markdown 代码块中有效使用差异语法高亮，请按照以下步骤操作：

• 使用三重反引号（```) 开始和结束栅栏代码块。
• 在打开反引号后立即指定 diff 作为语言标识符。这将启用差异语法高亮，类似于你在 Git 提交信息或拉取请求中看到的效果。

示例：

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

• 以 - 开头的行 将被高亮为删除（通常为红色）。
• 以 + 开头的行 将被高亮为添加（通常为绿色）。
• 没有前缀的行 不会特别高亮。

最佳实践：

• 使用此格式在文档、代码审查或技术博客中清晰地传达代码更改、修复或建议。
• 在代码块前后放置一个空行，以提高原始 Markdown 中的可读性。
• 请注意，差异高亮仅根据行首字符对整行进行颜色标记；它不会高亮行内更改。

提示：
此方法在 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!")
```

以下语言在 大多数 Markdown 渲染器 中广泛支持：

注意： 实际标识符可能有所不同（例如，js 与 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