关于 Markdown

Markdown 是一种轻量级标记语言，由 John Gruber 与 Aaron Swartz 于2004年创建。它使用简单的纯文本格式编写文档，然后转换成结构化的HTML页面，让非专业人士也能轻松编写格式丰富的文本。

“Markdown的目标是实现「易读易写」。” —— John Gruber

优势

简单易学：语法简洁明了，几分钟即可掌握基础用法
专注内容：减少排版干扰，让创作者专注于内容本身
跨平台兼容：纯文本格式，在任何设备上都能编辑查看
拓展能力强：原生支持内嵌HTML，可通过插件支持更多功能
导出灵活：可轻松转换为HTML、PDF、Word等多种格式
应用广泛：从代码文档到博客文章，生态系统完善

基础语法示例

# 一级标题
## 二级标题

**粗体文本** 和 *斜体文本*

- 无序列表项1
- 无序列表项2

1. 有序列表项1
2. 有序列表项2

[链接文本](https://example.com)

![图片描述](图片链接.jpg)

> 这是一段引用文本

`内联代码`

```代码块
function hello() {
  console.log("Hello, Markdown!");
}

应用场景

应用领域	说明
博客写作	大多数博客平台都支持Markdown格式
技术文档	GitHub、GitLab等代码托管平台的标准格式
AI对话	现代AI工具的标准交互格式，用户输入和AI回复均使用Markdown
协作办公	钉钉、飞书、Notion等办公工具广泛采用
公众号写作	通过专用编辑器转换为微信公众号格式

公众号Markdown工具

语法规范

Markdown有多种语法规范，各平台可能支持的语法略有不同：

CommonMark：最通用的基础语法规范，几乎所有Markdown工具都支持
GitHub Flavored Markdown (GFM)：GitHub对CommonMark的扩展，增加了：
- 表格及其对齐语法
- 任务列表（复选框）
- 删除线
- 自动链接识别
- 代码块语法高亮

各网站和应用通常在这些基础规范上，添加自己的特色功能，如：

@用户提及功能
#话题标签
数学公式支持（通常基于LaTeX）
图表绘制（如Mermaid、PlantUML等）

学习资源

入门教程：CommonMark交互式教程
GitHub语法：GitHub文档撰写指南

换行和分段详解

Markdown中最容易困惑的语法之一是换行和分段的区别：

分段 vs 换行

分段：使用空行（连续两次Enter）创建新段落，会产生段间距
换行：在同一段落内换行，不产生段间距

换行规则

不同Markdown解析器对换行的处理存在两种标准：

严格换行（CommonMark标准）：
- 硬换行：行末添加两个空格或反斜杠(\)才会在渲染时产生实际的换行
- 软换行：直接按回车在源码中换行，但渲染时这些换行会被忽略，文本依然在同一行显示
软换行的设计初衷是为了提高源代码的可读性，特别是对于长段落或包含多个链接的文本，作者可以在编辑时随意换行以提升源码可读性，而不影响最终的渲染效果。这体现了早期 Markdown 设计中”分离内容与显示”的理念。
简化换行（大多数现代编辑器的默认行为）：
- 源码中的所有换行都直接渲染为可见的换行，不区分软硬换行
简化换行规则变得流行有几个原因：
- 更符合直觉的所见即所得体验，减少学习障碍
- 现代编辑器已提供自动换行、语法高亮等功能，原本通过软换行解决的源码可读性问题已有更好的解决方案
- 特别在移动设备上，输入两个空格或反斜杠来实现换行过于繁琐
- 随着可视化编辑器的普及，复杂的源码格式规则变得不再必要

常见编辑器的换行设置

可配置的编辑器：
- VS Code：通过 markdown.preview.breaks 设置
- Obsidian：设置中的严格换行选项
混合规则：
- GitHub：Markdown文件预览区分软硬换行，但评论区不区分：GitHub换行规则
- 大多数现代编辑器：默认不区分软硬换行，更符合直觉

Markdown编译器

Markdown需要通过编译器渲染为HTML才能在网页中显示。常见的JavaScript编译器有：

markdown-it
- 特点：高速、可扩展、语法插件丰富
- 应用：VS Code 中的预览功能、VitePress 等
- 插件生态：官方插件列表
remark
- 特点：模块化设计、统一处理体系
- 应用：Astro、Next.js、Gatsby、Nuxt Content等
- 生态：unified体系的一部分

插件可以在使用相同编译器的不同框架之间通用，但如果跨到另一个编译器生态就需要找对应的替代实现。不过好在常见的功能在两个生态中通常都有对应的插件实现，只是使用方式和API可能有所不同。

嵌入框架组件

在Markdown中嵌入交互式组件有两种主要方案：

MDX

MDX允许在Markdown中直接使用JSX语法，可集成React、Vue、Svelte等框架组件：

# 标题

正常的Markdown内容

<Button onClick={() => alert('点击了')}>
  点击我
</Button>

继续Markdown内容

支持度：Next.js、Gatsby、Astro等主流框架默认或通过插件支持

MDC

MDC是Nuxt开发的语法，用于在Markdown中使用Vue组件：

# 标题

::vue-component{prop1="value" prop2="value"}
内容
::

继续Markdown内容

使用范围较小，主要在Nuxt生态系统中使用。

本站Markdown配置

本网站基于Astro框架，其Markdown支持由remark提供。当前配置了：

默认支持：GitHub Flavored Markdown
额外插件：
- @beoe/rehype-d2：支持D2图表语法
- remark-breaks：启用简化换行处理

想要扩展更多功能，可参考Astro Markdown文档添加插件。

D2 图表示例

D2 是一种声明式图表语言，可以快速创建流程图、架构图、ER图等。本站已配置 D2 支持，可以直接在 Markdown 中使用 D2 语法。

基本流程图示例

下面是一个简单的流程图示例：

组件关系图示例

下面展示一个组件关系图：

D2 语法提示

D2 图表的基本语法：

使用 -> 创建连接
使用 {} 定义嵌套结构或样式
使用 shape: 设置形状（rectangle, circle, person, cylinder 等）
使用 style.fill: 设置填充颜色

更多 D2 语法和示例请参考 D2 官方文档。