稚一1. Markdown基础语法完全指南
作为一名每天都要用Markdown写作的技术博主，我发现很多新手在刚接触这种轻量级标记语言时，总会遇到格式混乱、效果不如预期的问题。其实Markdown的核心理念就是用最简单的符号实现专业排版，今天我就把五年来的实战经验整理成这份万字手册。
Markdown本质上是一种纯文本格式的写作语法，它通过特定符号（如#、*、-等）来定义标题、列表、链接等元素。最大的优势是兼容性强，一份.md文件可以在GitHub、博客平台、笔记软件中保持一致的显示效果。对于程序员来说，它是写README的标配；对写作者而言，能专注内容而不被排版干扰；即便是普通用户，学会基础语法后做会议记录也比Word高效得多。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心语法详解与实战技巧
2.1 标题层级控制
标题是文档结构的骨架，Markdown用1-6个#符号对应HTML的h1-h6标签。建议这样使用：
markdown复制# 一级标题（建议单个文档只用1次）
## 二级标题（章节划分）
### 三级标题（子章节）
踩坑提醒：多数解析器要求#和文字间必须有空格，写成#错误示例 会解析失败。我习惯在标题后加空行，避免与下文粘连。
2.2 段落与换行
• 段落间用空行分隔（敲两次回车）
• 强制换行在行尾加2个空格（多数编辑器会高亮显示）
• 中文写作建议段首不缩进，用空行区分段落更清晰
实测案例：
markdown复制这是第一段（结尾无空格）
这是同一段的延续
这才是新段落（前面有空行）
需要换行处→
看到光标跳转了吗？
2.3 文本样式修饰
• 加粗：用双星号或下划线 **加粗** 或 __加粗__
• 斜体：单星号或下划线 *斜体* 或 _斜体_
• 删除线：双波浪线 ~~删除线~~
• 行内代码：反引号 `code`
混合样式示例：
markdown复制**重要**提示：请*立即*执行``rm -rf /*``命令（开玩笑的！）
3. 列表的进阶用法
3.1 无序列表的三种符号
- 减号+空格（我的首选）
- 星号+空格
- 加号+空格
专业建议：整个文档保持符号统一，混用虽然能解析但显得不专业。子列表缩进2或4空格：
markdown复制- 父项
- 子项（缩进2空格）
- 孙项（再缩进2空格）
3.2 有序列表的妙用
- 数字加点+空格（自动序号）
- 故意写相同数字
- 解析器会自动校正顺序
搭配嵌套使用：
markdown复制1. 主步骤
- 准备工作
- 注意事项
2. 下一步骤
4. 链接与图片的终极方案
4.1 超链接的三种写法
• 行内式：[文字](URL "可选标题")
• 参考式：[文字][id] 后文定义 [id]: URL
• 裸URL：<https://example.com>
我的习惯：
markdown复制详见[官方文档][docs]或直接访问<https://example.com>
[docs]: https://example.com/docs "最佳实践指南"
4.2 图片插入的隐藏技巧
基本语法类似链接，前面加!：
markdown复制
实战经验：
- 使用图床（如OSS）替代本地路径
- 用参考式链接管理大量图片
- 设置width属性需要HTML混编：
<img src="url" width="200">
5. 代码块的正确打开方式
5.1 行内代码与语法高亮
• 单行代码：前后各1个反引号
• 代码块：前后各3个反引号+语言名
markdown复制`print("行内代码")`
```python
def hello():
print("语法高亮代码块")
code复制
### 5.2 差异化显示方案
不同平台支持的语言不同：
- GitHub：支持300+语言
- VS Code：依赖插件
- 微信公众号：仅显示无高亮
我的多平台兼容方案：
````markdown
```bash
# 通用型代码
echo "Hello World"
code复制
## 6. 表格与高级排版技巧
### 6.1 极简表格制作
```markdown
| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 数据1 | 数据2 | 数据3 |
```
> 排版技巧：
1. 用VS Code插件（如Markdown All in One）自动格式化
2. 复杂表格建议用HTML的<table>标签
3. 避免单元格内换行，影响可读性
### 6.2 特殊符号转义
需要显示符号本身时加反斜杠：
```markdown
\*这不是斜体\*
\\ 反斜杠本身也要转义
```
## 7. 扩展语法与工具链
### 7.1 主流扩展语法
• 任务列表：`- [x] 已完成`
• 流程图：需特定插件支持
• 数学公式：`$$ E=mc^2 $$`
GitHub Flavored Markdown示例：
```markdown
- [ ] 购买食材
- [x] 准备厨具
```
### 7.2 我的写作工具推荐
1. **编辑器**：
- VS Code + Markdown插件套件
- Typora（实时渲染）
2. **图床**：
- PicGo + GitHub仓库
- 阿里云OSS
3. **校验工具**：
- markdownlint-cli
- 在线预览工具StackEdit
## 8. 常见问题与排错指南
### 8.1 解析不一致问题
现象：在不同平台显示效果不同
解决方案：
1. 检查空行是否足够
2. 避免混用扩展语法
3. 用CommonMark标准语法
### 8.2 图片无法加载
排查步骤：
1. 检查URL是否有效
2. 确认图床无防盗链
3. 尝试用浏览器直接访问图片链接
### 8.3 特殊字符冲突
高频问题：
- 邮件地址中的@要用``包围
- 中文引号与Markdown符号冲突
- 列表项包含冒号时可能被误解析
## 9. 我的Markdown工作流
### 9.1 文档结构模板
```markdown
# 标题
[TOC] <!-- 部分编辑器支持自动生成目录 -->
## 1. 概述
## 2. 正文
### 2.1 子章节
## 附录
```
### 9.2 版本控制技巧
1. 用Git管理.md文件
2. 每个章节单独提交
3. 用diff工具比较修改
最后分享一个冷知识：在VS Code中按`Ctrl+K v`可以打开实时预览窗口，这是我每天必用的快捷键组合。记住Markdown的本质是内容优先，当你在纠结某个符号效果时，不妨想想——如果纯文本能表达清楚，那就是最好的排版。