Markdown写作与文档管理完整教程：高效创作指南
我写技术文章五年了，从Word转到Markdown后再没回去。Markdown简单高效，专注内容不用管排版，写完自动格式化。博客、文档、笔记、README全用它。今天把Markdown从入门到精通的方法分享出来，帮你高效写作。
什么是Markdown
Markdown是一种轻量级标记语言，用简单符号标记格式。
比如：#表示标题，**加粗**表示加粗，-表示列表。写的时候用符号标记，渲染后自动变成格式。
对比Word的优势：
1. 纯文本，体积小，任何编辑器都能打开。
2. 格式统一，不用手动调排版。
3. 版本控制友好，Git能diff。
4. 跨平台，不依赖特定软件。
5. 专注内容，不被排版打断思路。
6. 可转HTML、PDF、Word等多种格式。
现在GitHub、简书、CSDN、知乎都支持Markdown，技术写作标配。
基础语法
核心语法就几个，5分钟学会。
标题：用#号，几个#就是几级标题。
# 一级标题
## 二级标题
### 三级标题
最多到六级。#和文字之间有空格。
段落：空行分段。两段之间空一行。
换行：行末两个空格或<br>。
加粗：**文字**或__文字__。
斜体：*文字*或_文字_。
加粗斜体：***文字***。
删除线：~~文字~~。
引用：> 引用内容。
无序列表：- 或* 或+开头。
- 项目一
- 项目二
- 子项目（缩进2空格）
有序列表：数字加点。
1. 第一项
2. 第二项
代码：行内用反引号包裹`code`。代码块用三个反引号。
```
代码块
```
指定语言有语法高亮：
```javascript
console.log("hello");
```
链接：[文字](URL)。例如[百度](https://baidu.com) 。
图片：。例如。
分割线：三个或更多---或***。
表格：
| 列1 | 列2 | 列3 |
|------|------|------|
| a | b | c |
| d | e | f |
第二行的:控制对齐：:---左对齐，:---:居中，---:右对齐。
这些是基础，掌握这些就能写大部分文档了。
进阶语法
一些进阶功能：
任务列表：
- [x] 已完成
- [ ] 未完成
脚注：
正文文字[^1]
[^1]: 脚注内容
定义列表（部分编辑器支持）：
术语
: 定义
行内HTML：Markdown支持直接写HTML标签。比如<details>折叠内容，<kbd>按键样式。
数学公式（部分平台支持）：$E=mc^2$行内，$$公式$$块级。
流程图（部分平台支持）：用mermaid语法画图。
锚点：[跳转](#标题)。标题转小写、空格变横线。
注释：<!--注释-->。HTML注释，渲染不显示。
这些进阶功能不是所有平台都支持，用之前确认。
编辑器选择
好编辑器让Markdown写作更高效。
1. VS Code：装Markdown All in One和Markdown Preview Enhanced插件。写作+预览+功能全。我主力用这个。
2. Typora：所见即所得，写的时候就是最终效果。付费了（$14.99买断），但体验好。
3. Obsidian：笔记+Markdown，双链功能强。免费。
4. MarkText：免费开源的Typora替代品，所见即所得。
5. 印象笔记/有道云笔记：支持Markdown。
6. 在线工具：StackEdit、Dillinger，不用装软件。
7. GitHub：直接在线编辑README。
我日常用VS Code写，简单快速记录用Obsidian。长文章用Typora（如果有）。
VS Code Markdown配置
VS Code写Markdown的优化配置：
装插件：
1. Markdown All in One：快捷键、目录、列表等增强。必装。
2. Markdown Preview Enhanced：预览增强，支持图表、公式、导出。
3. markdownlint：语法检查，提示格式问题。
4. Paste Image：粘贴图片自动保存到目录并插入链接。
settings.json配置：
"markdown.preview.fontSize": 16,
"markdown.preview.lineHeight": 1.6,
"markdown.extension.toc.levels": "2..6", // 目录层级
"markdown.extension.toc.orderedList": true, // 有序目录
"markdown.extension.preview.autoShowPreviewToSide": true, // 侧边预览
常用快捷键：
Ctrl+B：加粗。
Ctrl+I：斜体。
Ctrl+Shift+V：预览。
Ctrl+K V：侧边预览。
Alt+S：切换删除线。
Ctrl+Shift+]：标题升级。
Ctrl+Shift+[：标题降级。
Alt+C：任务列表勾选。
这些快捷键用熟，写作效率很高。
图片管理
Markdown图片管理是个痛点，图片存哪、怎么引用。
方案一：本地引用
图片放在文档同目录或子目录，用相对路径引用。。适合本地文档。
方案二：图床
图片传到图床，用URL引用。常见图床：GitHub、七牛云、阿里云OSS、SM.MS。适合博客。
方案三：Base64内嵌
图片转Base64编码直接嵌在Markdown里。优点是单文件，缺点是文件大。适合小图标。
方案四：云存储
用阿里云OSS、腾讯云COS等对象存储。稳定可靠，适合长期。
我用PicGo+阿里云OSS管理图片。截图后PicGo自动上传，返回URL，粘贴到Markdown。
PicGo配置：
1. 下载PicGo（免费）。
2. 配置图床（阿里云OSS、腾讯云COS等）。
3. 截图后在PicGo上传，自动复制URL。
4. VS Code装Paste Image插件，截图直接粘贴，自动上传（需配合脚本）。
这套方案用了两年，图片管理很顺畅。
文档模板
用模板提高效率，常见模板：
技术文章模板：
# 标题
## 背景
为什么写这篇文章，解决什么问题。
## 环境准备
需要什么工具、版本。
## 步骤
### 第一步
详细步骤。
### 第二步
## 常见问题
## 总结
API文档模板：
# 接口名称
## 请求
- URL: /api/xxx
- 方法: POST
- 参数:
| 参数 | 类型 | 必填 | 说明 |
## 响应
```json
{ "code": 0, "data": {} }
```
## 示例
README模板：
# 项目名
一句话描述。
## 功能
- 功能1
- 功能2
## 安装
```bash
npm install
```
## 使用
## 配置
## 贡献
## 许可证
模板存起来，新建文档复制改，效率高。
导出格式
Markdown能转多种格式：
转HTML：用VS Code Markdown Preview Enhanced导出，或pandoc命令。
转PDF：VS Code插件Markdown PDF，或Typora导出，或pandoc。
转Word：pandoc file.md -o file.docx。
转HTML幻灯片：pandoc file.md -o file.html -t revealjs，做演示文稿。
pandoc是格式转换神器，命令行工具，支持几十种格式互转。
我写完Markdown用pandoc转PDF或Word分享给别人。
写作工作流
我的Markdown写作流程：
1. 在Obsidian或VS Code新建Markdown文件。
2. 先写大纲（标题结构），理清思路。
3. 逐节填充内容，专注写不管排版。
4. 插入图片（PicGo上传粘贴URL）。
5. 检查格式，用markdownlint提示修正。
6. 预览确认效果。
7. 导出需要的格式。
8. 发布到博客/平台。
这个流程用了三年，写作效率很高，一天能写几千字。
多平台发布
Markdown文章可以发到多个平台：
1. GitHub：README、Wiki、Issues都支持Markdown。
2. 个人博客：Hexo、Hugo、Jekyll等静态博客用Markdown。
3. 简书：直接粘贴Markdown。
4. CSDN：支持Markdown编辑器。
5. 知乎：支持Markdown导入。
6. 掘金：支持Markdown。
7. 微信公众号：用Markdown转换工具（如mdnice）排版。
我用mdnice把Markdown转成公众号格式，排版好看，省了大量排版时间。
mdnice使用：
1. 打开mdnice.com。
2. 粘贴Markdown内容。
3. 选主题样式。
4. 复制到公众号。
一键排版，公众号文章专业美观。
团队文档管理
团队用Markdown管理文档：
1. 用Git仓库存文档，版本可追溯。
2. 配合GitHub/GitLab Wiki。
3. 用Docsify或VuePress搭建文档站。
4. 统一模板和规范。
5. 文档跟代码一起存，同步更新。
我们团队所有文档都用Markdown+Git，改了提交，有记录可追溯。
写作技巧
Markdown写作的一些技巧：
1. 先写大纲再填内容，别想到哪写到哪。
2. 标题层级别跳（别从二级跳到四级）。
3. 代码块标语言，有语法高亮。
4. 图片要有描述文字。
5. 表格别太宽，手机看不了。
6. 段落别太长，3-5行一段。
7. 重点用加粗，别整段加粗。
8. 善用列表，步骤清晰。
9. 写完检查一遍格式。
10. 保存模板，复用。
常见问题
问题1：表格太复杂怎么办
Markdown表格功能有限，复杂表格用HTML表格标签。
问题2：怎么调整图片大小
标准Markdown不支持调大小。用HTML：<img src="url" width="500">。或用图片处理工具调好再上传。
问题3：脚注不显示
不是所有平台支持脚注。需要的话用链接代替。
问题4：特殊字符显示异常
特殊字符（* _ #等）用反斜杠转义。*显示实际的*。
问题5：换行不生效
Markdown里直接换行不会换行。行末加两个空格，或空行分段。
我的Markdown工具链
我的完整工具链：
编辑器：VS Code + Markdown All in One + Markdown Preview Enhanced。
笔记：Obsidian。
图片：PicGo + 阿里云OSS。
格式转换：pandoc。
公众号排版：mdnice。
博客：Hexo。
文档站：Docsify。
版本管理：Git。
这套工具链用了三年，写作流程顺畅高效。
总结
Markdown是技术写作的标配，5分钟学会基础语法，一辈子受用。核心是：#标题、**加粗**、-列表、`代码`、[]()链接、![]()图片。选好编辑器（VS Code或Typora），配好图片管理（PicGo），建好模板。专注内容，不管排版，写作效率翻倍。不管是写博客、记笔记、做文档，Markdown都是最佳选择。
