Markdown 完整语法指南

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建。它允许你使用易读易写的纯文本格式编写文档，然后转换成结构化的 HTML。本指南将全面介绍 Markdown 的各种语法，并展示本博客的增强功能。

基础语法

标题

Markdown 支持六级标题，使用 # 符号表示。# 的数量对应标题的级别：

# 一级标题 (H1)

## 二级标题 (H2)

### 三级标题 (H3)

#### 四级标题 (H4)

##### 五级标题 (H5)

###### 六级标题 (H6)

效果展示：

一级标题示例

二级标题示例

三级标题示例

四级标题示例

五级标题示例

六级标题示例

💡 提示：本博客支持标题锚点链接功能，点击任意标题即可获取该标题的直接链接，方便分享和引用。

段落和换行

在 Markdown 中，段落由一个或多个空行分隔。如果需要在段落内换行（软换行），可以在行尾添加两个或更多空格，然后按回车键。

这是第一个段落。

这是第二个段落。

这是一行文字。
这是同一段落的下一行（行尾有两个空格）。

效果展示：

这是第一个段落。

这是第二个段落。

这是一行文字。
这是同一段落的下一行（行尾有两个空格）。

强调

Markdown 提供多种文本强调方式：

**粗体文本** 或 **粗体文本**

_斜体文本_ 或 _斜体文本_

**_粗斜体文本_** 或 **_粗斜体文本_**

~~删除线文本~~

这是一段包含 **粗体**、_斜体_ 和 ~~删除线~~ 的混合文本。

效果展示：

粗体文本 或 粗体文本

斜体文本 或 斜体文本

粗斜体文本 或 粗斜体文本

~~删除线文本~~

这是一段包含粗体、斜体和 ~~删除线~~ 的混合文本。

引用块

使用 > 符号创建引用块，可以嵌套使用：

> 这是一段引用文本。
>
> 引用可以包含多个段落。

> 第一层引用
>
> > 第二层嵌套引用
> >
> > > 第三层嵌套引用

效果展示：

这是一段引用文本。

引用可以包含多个段落。

第一层引用

第二层嵌套引用

第三层嵌套引用

引用中的格式化

引用块中可以使用其他 Markdown 语法：

列表项

粗体和斜体

行内代码

列表

无序列表

使用 -、* 或 + 创建无序列表：

- 项目一
- 项目二
- 项目三

* 另一种写法
* 项目二
* 项目三

效果展示：

项目一
项目二
项目三

有序列表

使用数字加点号创建有序列表：

1. 第一步
2. 第二步
3. 第三步

效果展示：

第一步
第二步
第三步

嵌套列表

列表可以嵌套，使用缩进（2或4个空格）表示层级：

- 主项目一
  - 子项目 1.1
  - 子项目 1.2
    - 子子项目 1.2.1
- 主项目二
  1. 有序子项目 2.1
  2. 有序子项目 2.2
- 主项目三

效果展示：

主项目一
- 子项目 1.1
- 子项目 1.2
  - 子子项目 1.2.1
主项目二
1. 有序子项目 2.1
2. 有序子项目 2.2
主项目三

链接

Markdown 支持多种链接格式：

[内联链接](https://example.com)

[带标题的链接](https://example.com '链接标题')

[引用式链接][reference]

[reference]: https://example.com '引用式链接'

自动链接：<https://example.com>

效果展示：

内部链接：

外部链接（注意外部链接图标）：

Astro 官方网站 - 现代化的静态网站生成器
GitHub - 全球最大的代码托管平台
MDN Web Docs - Mozilla 的 Web 技术文档
CommonMark 规范 - Markdown 标准规范

💡 提示：本博客会自动为外部链接添加图标标识，帮助读者区分内部链接和外部链接。

图片

使用以下语法插入图片：

![替代文本](图片URL)

![带标题的图片](图片URL '图片标题')

效果展示：

💡 提示：本博客支持图片灯箱功能，点击任意图片即可放大查看，再次点击或按 ESC 键关闭。

水平分割线

使用三个或更多的 -、* 或 _ 创建水平分割线：

---
---

---

效果展示：

代码

行内代码

使用反引号 ` 包裹行内代码：

使用 `console.log()` 输出调试信息。

安装依赖：`npm install`

变量 `const x = 10` 是常量。

效果展示：

使用 console.log() 输出调试信息。

安装依赖：npm install

变量 const x = 10 是常量。

如果代码中包含反引号，可以使用双反引号：

`` `code` `` 显示带反引号的代码

效果展示：

`code` 显示带反引号的代码

代码块

使用三个反引号创建代码块，并指定语言以启用语法高亮：

💡 提示：本博客的代码块支持以下增强功能：

语言标题：自动显示代码语言

一键复制：点击复制按钮即可复制代码

JavaScript

// JavaScript 示例：异步函数和 Promise
async function fetchUserData(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`)
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    const data = await response.json()
    return data
  } catch (error) {
    console.error('获取用户数据失败:', error)
    throw error
  }
}

// 使用示例
fetchUserData(123)
  .then((user) => console.log('用户信息:', user))
  .catch((err) => console.error('错误:', err))

TypeScript

// TypeScript 示例：接口和泛型
interface User {
  id: number
  name: string
  email: string
  createdAt: Date
}

interface ApiResponse<T> {
  data: T
  status: number
  message: string
}

async function fetchData<T>(url: string): Promise<ApiResponse<T>> {
  const response = await fetch(url)
  const data: T = await response.json()

  return {
    data,
    status: response.status,
    message: response.ok ? 'Success' : 'Error',
  }
}

// 使用泛型函数
const userResponse = await fetchData<User>('/api/user/1')
console.log(userResponse.data.name)

Python

# Python 示例：类和装饰器
from functools import wraps
from typing import Callable, Any
import time

def timer(func: Callable) -> Callable:
    """计时装饰器"""
    @wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        start = time.perf_counter()
        result = func(*args, **kwargs)
        end = time.perf_counter()
        print(f'{func.__name__} 执行时间: {end - start:.4f} 秒')
        return result
    return wrapper

class DataProcessor:
    """数据处理类"""

    def __init__(self, data: list[int]):
        self.data = data

    @timer
    def process(self) -> list[int]:
        """处理数据：过滤、映射、排序"""
        result = [x * 2 for x in self.data if x > 0]
        return sorted(result, reverse=True)

# 使用示例
processor = DataProcessor([3, -1, 4, 1, 5, -9, 2, 6])
result = processor.process()
print(f'处理结果: {result}')

CSS

/* CSS 示例：现代布局和变量 */
:root {
  --primary-color: #3b82f6;
  --secondary-color: #10b981;
  --text-color: #1f2937;
  --bg-color: #ffffff;
  --spacing-unit: 1rem;
}

.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: calc(var(--spacing-unit) * 2);
}

.card {
  background: var(--bg-color);
  border-radius: 0.5rem;
  box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  padding: var(--spacing-unit);
  transition:
    transform 0.2s ease,
    box-shadow 0.2s ease;
}

.card:hover {
  transform: translateY(-2px);
  box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}

/* 响应式网格布局 */
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--spacing-unit);
}

@media (max-width: 768px) {
  .container {
    padding: var(--spacing-unit);
  }
}

HTML

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="示例页面描述" />
    <title>示例页面</title>
    <link rel="stylesheet" href="/styles/main.css" />
  </head>
  <body>
    <header class="header">
      <nav class="nav">
        <a href="/" class="logo">Logo</a>
        <ul class="nav-links">
          <li><a href="/about">关于</a></li>
          <li><a href="/posts">文章</a></li>
          <li><a href="/contact">联系</a></li>
        </ul>
      </nav>
    </header>

    <main class="main">
      <article class="post">
        <h1>文章标题</h1>
        <p>文章内容...</p>
      </article>
    </main>

    <footer class="footer">
      <p>&copy; 2024 我的网站</p>
    </footer>

    <script src="/scripts/main.js" defer></script>
  </body>
</html>

Bash / Shell

#!/bin/bash

# Bash 示例：项目初始化脚本

set -e  # 遇到错误立即退出

PROJECT_NAME=${1:-"my-project"}
TEMPLATE=${2:-"default"}

echo "🚀 创建项目: $PROJECT_NAME"

# 创建项目目录
mkdir -p "$PROJECT_NAME"/{src,public,tests}
cd "$PROJECT_NAME"

# 初始化 package.json
cat > package.json << EOF
{
  "name": "$PROJECT_NAME",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  }
}
EOF

# 安装依赖
echo "📦 安装依赖..."
npm install vite vitest --save-dev

# 创建示例文件
echo "console.log('Hello, $PROJECT_NAME!');" > src/main.js

echo "✅ 项目创建完成！"
echo "   cd $PROJECT_NAME && npm run dev"

JSON

{
  "name": "my-astro-blog",
  "version": "1.0.0",
  "description": "一个使用 Astro 构建的博客",
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "astro": "^4.0.0",
    "@astrojs/mdx": "^2.0.0",
    "@astrojs/sitemap": "^3.0.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "prettier": "^3.1.0"
  },
  "keywords": ["astro", "blog", "markdown"],
  "author": "Your Name",
  "license": "MIT"
}

YAML

# YAML 示例：网站配置文件
site:
  title: '我的博客'
  description: '分享技术与生活'
  url: 'https://example.com'
  language: 'zh-CN'

author:
  name: '张三'
  email: 'zhangsan@example.com'
  social:
    github: 'https://github.com/zhangsan'
    twitter: 'https://twitter.com/zhangsan'

navigation:
  - title: '首页'
    url: '/'
  - title: '文章'
    url: '/posts'
  - title: '关于'
    url: '/about'

features:
  darkMode: true
  comments: true
  search: true
  rss: true

build:
  output: 'dist'
  minify: true
  sourcemap: false

扩展语法

表格

使用 | 和 - 创建表格：

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1  |  内容2   |  内容3 |
| 内容4  |  内容5   |  内容6 |

效果展示：

功能	语法	示例	说明
粗体	`text`	粗体	使用双星号包裹
斜体	`text`	斜体	使用单星号包裹
删除线	`~~text~~`	删除	使用双波浪线包裹
行内代码	`code`	`code`	使用反引号包裹
链接	`[text](url)`	链接	方括号加圆括号

更复杂的表格示例：

编程语言	类型系统	主要用途	流行框架
JavaScript	动态类型	Web 前端、Node.js 后端	React, Vue, Angular
TypeScript	静态类型	大型 Web 应用	Next.js, NestJS
Python	动态类型	数据科学、AI、后端	Django, FastAPI, Flask
Rust	静态类型	系统编程、WebAssembly	Actix, Rocket
Go	静态类型	云原生、微服务	Gin, Echo

任务列表

使用 - [ ] 和 - [x] 创建任务列表：

- [x] 已完成的任务
- [x] 另一个已完成的任务
- [ ] 待完成的任务
- [ ] 另一个待完成的任务

效果展示：

项目开发清单：

学习计划：

脚注

使用 [^标识] 创建脚注：

这是一个带有脚注的句子[^1]。

这是另一个脚注示例[^note]。

[^1]: 这是第一个脚注的内容。

[^note]: 这是命名脚注的内容，可以包含更详细的说明。

效果展示：

Markdown 是由 John Gruber 创建的¹，最初发布于 2004 年²。它的设计目标是让文档既易于阅读又易于编写³。

如今，Markdown 已经成为技术写作的事实标准，被广泛应用于文档编写、博客发布和代码注释等场景⁴。

定义列表

某些 Markdown 解析器支持定义列表（本博客可能需要特定配置）：

术语 1
: 术语 1 的定义

术语 2
: 术语 2 的第一个定义
: 术语 2 的第二个定义

效果展示：

Markdown : 一种轻量级标记语言，用于格式化纯文本文档。

HTML : 超文本标记语言，用于创建网页的标准标记语言。

CSS : 层叠样式表，用于描述 HTML 文档的呈现方式。

本博客增强功能

本博客基于 Astro 构建，提供了以下 Markdown 增强功能：

1. 代码块增强

每个代码块都具有以下功能：

语言标识：代码块顶部显示编程语言名称
一键复制：点击复制按钮即可复制整个代码块内容
语法高亮：支持多种编程语言的语法高亮

// 试试点击右上角的复制按钮！
const greeting = 'Hello, World!'
console.log(greeting)

2. 标题锚点链接

所有标题（h1-h6）都自动生成锚点链接：

鼠标悬停在标题上会显示链接图标
点击标题可以获取该章节的直接链接
方便分享文章的特定部分

3. 图片灯箱效果

文章中的图片支持灯箱功能：

点击图片可以放大查看
支持键盘导航（ESC 关闭）
点击遮罩层关闭灯箱

4. 外部链接图标

外部链接会自动添加图标标识：

内部链接：首页 - 无图标
外部链接：Astro 官网 - 有图标

这帮助读者快速识别链接是否会离开当前网站。

写作最佳实践

1. 结构清晰

使用标题层级组织内容，不要跳级
每个章节保持适当的长度
使用分割线分隔主要部分

2. 代码规范

始终为代码块指定语言
添加必要的注释说明
保持代码简洁，突出重点

3. 图片使用

为图片添加有意义的替代文本
使用适当大小的图片
考虑图片的加载性能

4. 链接管理

使用描述性的链接文本
检查链接的有效性
适当使用内部链接增加关联性

总结

Markdown 是一种简单而强大的写作工具。通过本指南，你已经了解了：

基础语法：标题、段落、强调、列表、链接、图片等
代码展示：行内代码和多语言代码块
扩展语法：表格、任务列表、脚注等
博客增强：代码复制、标题锚点、图片灯箱、外部链接图标

掌握这些语法后，你就可以轻松创建格式优美、结构清晰的文章了。

参考资源

CommonMark 规范 - Markdown 标准规范
GitHub Flavored Markdown - GitHub 扩展语法
Astro 文档 - Astro 框架官方文档
MDN Web Docs - Web 技术参考文档

本文最后更新于 2024 年 1 月 10 日

John Gruber 是一位美国博主和 UI 设计师，也是 Daring Fireball 博客的作者。 ↩
Markdown 的首个版本于 2004 年 3 月 19 日发布。 ↩
Markdown 的核心理念是”易读易写”，源文档应该可以直接发布而无需转换。 ↩
GitHub、Stack Overflow、Reddit 等平台都支持 Markdown 格式。 ↩