Markdown 完全指南：从入门到精通，程序员必会的轻量标记语言

Markdown 完全指南从入门到精通程序员必会的轻量标记语言文章目录 Markdown 完全指南从入门到精通程序员必会的轻量标记语言 Markdown 是什么 一、标题✍️ 二、文字样式 三、列表无序列表有序列表嵌套列表缩进 2 或 4 个空格任务列表GitHub 风格 四、代码行内代码代码块代码块进阶显示文件名部分平台图片给图片添加链接点击图片跳转 六、表格 七、引用➖ 八、分割线 九、转义字符 十、HTML 支持 十二、GitHub README 最佳实践基础用法 文档 贡献 许可证 十三、AI 开发场景专项Jupyter Notebook 里的 Markdown Cell写技术博客的结构模板 核心实战 效果对比️ 读者互动 总结速查️ 十四、常用工具推荐❌ 十五、常见错误速查错误 1标题 # 后没有空格错误 2列表项前没有空行某些平台错误 3代码块语言标识符写错错误 4表格列数不对齐错误 5图片路径错误 语法速查总表写在前面GitHub README、CSDN 博客、Notion 笔记、Jupyter Notebook、VitePress 文档……你每天接触的技术内容背后几乎都是 Markdown 写的。Markdown 是程序员写作的基础技能学一次到处用。这篇从基础语法到进阶技巧再到 AI 开发的实际场景把 Markdown 彻底讲清楚。建议收藏写文档时随时翻。 Markdown 是什么Markdown 是 John Gruber 在 2004 年发明的轻量级标记语言核心理念用纯文本写作用少量符号表达格式 让源码本身就容易阅读渲染后更漂亮。一个最简单的例子纯文本写这个# 这是标题 这是一段**加粗**的文字还有 代码。 - 列表项 1 - 列表项 2渲染后就变成了带格式的文章。Markdown 在哪里用平台/工具用途GitHub / GitLabREADME、Issue、PR 描述CSDN / 掘金 / 知乎技术博客写作Notion / Obsidian笔记管理Jupyter Notebook数据分析笔记本VitePress / Docusaurus项目文档VS Code文档预览内置ChatGPT / ClaudeAI 的回答格式 一、标题用#表示标题层级1-6 级# 一级标题H1一篇文章只用一个 ## 二级标题H2主要章节 ### 三级标题H3子章节 #### 四级标题H4 ##### 五级标题H5 ###### 六级标题H6最小很少用注意#后面必须有一个空格。#标题 ← 错误不会被识别 # 标题 ← 正确✍️ 二、文字样式**加粗文字** → **加粗** *斜体文字* → *斜体* ***加粗斜体*** → ***加粗斜体*** ~~删除线~~ → ~~删除线~~ 行内代码 → 代码样式 u下划线/u → 下划线HTML 写法 高亮 → 高亮部分平台支持实际使用场景安装 numpy 库需要运行 pip install numpy。 **注意**在生产环境中**不要**使用 debugTrue。 这个方法已经~~被废弃了~~请使用新版 API。 三、列表无序列表用-、*或效果相同推荐用-- Python - JavaScript - Rust * 也可以用星号 或者加号有序列表1. 第一步安装依赖 2. 第二步配置环境变量 3. 第三步启动服务技巧有序列表的数字不必连续Markdown 自动处理编号1. 第一步 1. 第二步写 1. 也行渲染出来是 2. 1. 第三步嵌套列表缩进 2 或 4 个空格- 前端框架 - React - Next.js - Remix - Vue - Nuxt.js - 后端框架 - FastAPIPython - ExpressNode.js任务列表GitHub 风格- [x] 已完成的任务 - [ ] 未完成的任务 - [x] 安装 Python 环境 - [ ] 配置 CUDA - [ ] 跑通第一个训练实验 四、代码代码是技术文章最重要的元素Markdown 的代码支持非常好。行内代码用反引号包裹使用 torch.cuda.is_available() 检查 GPU 是否可用。代码块三个反引号 开始和结束强烈建议指定语言语法高亮python import torch model torch.nn.Linear(4096, 4096) print(f参数量{sum(p.numel() for p in model.parameters()):,}) 常用语言标识符语言标识符PythonpythonJavaScriptjavascript/jsTypeScripttypescript/tsBash/Shellbash/shellJSONjsonYAMLyamlSQLsqlMarkdownmarkdown/mdHTMLhtmlCSScssC/Cc/cppJavajavaGogoRustrust不指定语言空白无高亮代码块进阶显示文件名部分平台python titletrain.py def main(): pass--- ## 五、链接与图片 ### 链接 markdown [显示文字](https://url.com) [显示文字](https://url.com 鼠标悬停提示) !-- 参考式链接适合多处引用同一 URL-- [GitHub][github-link] [HuggingFace][hf-link] [github-link]: https://github.com [hf-link]: https://huggingface.co图片  给图片添加链接点击图片跳转[](跳转URL) 六、表格| 左对齐 | 居中 | 右对齐 | |:---|:---:|---:| | 内容 | 内容 | 内容 | | Python | ★★★★★ | 2025年 | | Rust | ★★★★ | 2024年 |渲染效果左对齐居中右对齐Python★★★★★2025年Rust★★★★2024年表格对齐语法:---左对齐默认:---:居中---:右对齐实用技巧表格内容不能换行复杂表格建议用 HTMLtable。 七、引用 这是一段引用文字。 多行引用 可以这样写 每行都加 引用里可以嵌套其他格式 **加粗**、代码、列表都可以 第一层引用 第二层引用嵌套 第三层引用实际用法 **提示**修改配置文件后需要重启服务才能生效。 **⚠️ 警告**以下操作会删除所有数据请先备份➖ 八、分割线三个或更多---、***或___上面的内容 --- 下面的内容 九、转义字符Markdown 有些特殊字符*、_、#、、\等要显示原字符需要用\转义\*这不是斜体\* \这不是代码\ \# 这不是标题 1\. 这不是有序列表 十、HTML 支持Markdown 支持直接嵌入 HTML大多数平台允许!-- 注释不会显示 -- details summary点击展开更多内容/summary 这里是折叠起来的内容默认不显示。 python print(Hello World)项目 Logo红色文字**details 折叠块在 GitHub README 里非常实用**可以把安装说明、版本历史等折叠起来保持页面整洁。 --- ## 十一、数学公式LaTeX 大多数技术文档平台支持 LaTeX 数学公式CSDN 支持GitHub 也已支持 markdown !-- 行内公式用单个 $ 包裹 -- 注意力机制的缩放因子是 $\sqrt{d_k}$防止点积过大。 !-- 块级公式用 $$ 包裹 -- $$ \text{Attention}(Q, K, V) \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$ !-- LoRA 参数更新公式 -- $$ W W_0 \Delta W W_0 BA, \quad B \in \mathbb{R}^{d \times r}, A \in \mathbb{R}^{r \times k} $$常用 LaTeX 符号速查\alpha \beta \gamma \theta % 希腊字母 \sum \prod \int % 求和/乘积/积分 \frac{a}{b} % 分数 \sqrt{x} % 平方根 x^2 x_i % 上标/下标 \mathbf{W} \mathbb{R} % 粗体/双线字母 \left( \right) % 自适应括号 \approx \neq \leq \geq % 约等/不等/大小 \in \notin \subset % 集合符号 十二、GitHub README 最佳实践GitHub README 是最常写的 Markdown 文档有一套约定俗成的结构# 项目名称 [](链接) [](https://opensource.org/licenses/MIT) 一句话描述这个项目是什么。 ## ✨ 功能特性 - 功能 1 - 功能 2 - 功能 3 ## 快速开始 ### 安装 bash pip install your-package基础用法fromyour_packageimportYourClass objYourClass()obj.do_something() 文档详细文档请查看 文档站点 贡献欢迎提交 PR请先阅读 贡献指南 许可证本项目使用 MIT 许可证### 徽章Badges生成 访问 [shields.io](https://shields.io) 自动生成各种徽章 markdown !-- GitHub Stars --  !-- PyPI 版本 --  !-- 许可证 --  !-- Python 版本 --  十三、AI 开发场景专项Jupyter Notebook 里的 Markdown Cell## 实验配置 | 参数 | 值 | 说明 | |---|---|---| | 模型 | Qwen3-7B | 基础模型 | | 训练数据 | 5,000 条 | alpaca_zh 子集 | | 学习率 | 2e-4 | 余弦退火 | | Batch Size | 324卡 × 2 × 4 梯度累积| | | Epochs | 1 | | ## 结果分析 训练 loss 从 **2.84** 降至 **1.38**下降约 **51%**。 **结论**模型在中文指令跟随任务上表现出明显改善。写技术博客的结构模板# 文章标题技术名称 场景 价值 [TOC](文章目录) **写在前面**一句话说明这篇文章解决什么问题 以及读完能获得什么收益。 --- ## 背景与原理 [为什么需要这个技术/工具] ## 安装与配置 bash pip install ... 核心实战[代码 解释 注意事项] 效果对比[数据/截图/表格]️ 读者互动评论区留下你的问题 总结速查[一张表/速查清单] 相关阅读 | 参考资料### 论文笔记 Markdown 模板 markdown # 论文笔记[论文标题] **作者**xxx et al. **发表**arXiv 2026.01 / ICLR 2026 **链接**[arXiv](https://arxiv.org/abs/xxxx.xxxxx) --- ## 核心贡献一句话 [用自己的话概括最重要的创新点] ## 方法 ### 问题定义 [公式 解释] $$\mathcal{L} ...$$ ### 核心方法 [图 解释] ## 实验结果 | Benchmark | 本文方法 | SOTA | Baseline | |---|---|---|---| | MMLU | 92.8% | 93.0% | 89.5% | ## 个人理解 [自己的思考、疑问、与已有方法的联系] ## ❓ 还没搞懂的地方 - [ ] 公式 (3) 中 XXX 是怎么推导的 - [ ] 为什么选择 XXX 而不是 YYY️ 十四、常用工具推荐工具平台特点TyporaWindows/Mac所见即所得最流畅的写作体验Obsidian全平台双链笔记知识库管理VS Code全平台内置预览配合插件很强大Mark Text全平台开源免费类似 TyporaHackMD在线协作编辑实时预览Notion在线Markdown 数据库功能更丰富VS Code 必装插件Markdown All in One快捷键、目录生成、数学公式Markdown Preview Enhanced更强大的预览支持图表markdownlint语法检查保证格式规范❌ 十五、常见错误速查错误 1标题 # 后没有空格#错误标题 ← 不会被识别为标题 # 正确标题 ← 这才对错误 2列表项前没有空行某些平台正文内容 - 列表项1 ← 某些解析器不识别紧跟正文 正文内容 - 列表项1 ← 空一行更保险错误 3代码块语言标识符写错Pyhton ← 拼错了不会高亮 Python ← 大小写也可能影响建议全小写 python ← 正确错误 4表格列数不对齐| 标题1 | 标题2 | ← 2 列 |---|---|---| ← 3 列错误 | 内容 | 内容 | ← 2 列错误 5图片路径错误 ← 相对路径要确认文件在同目录  ← 绝对路径相对网站根目录  ← 显式相对路径最清晰 语法速查总表# 标题1 ## 标题2 ### 标题3 **加粗** *斜体* ***加粗斜体*** ~~删除线~~ 行内代码 - 无序列表项 1. 有序列表项 - [x] 任务列表已完成 [链接文字](https://url.com)  | 列1 | 列2 | 列3 | |:---|:---:|---:| | 左对齐 | 居中 | 右对齐 | 引用文字 ---分割线 python 代码块--- ## 最后 如果这篇让你把 Markdown 彻底搞清楚了 - **点赞** 让更多学技术写作的同学看到 - ⭐ **收藏** 写文档时直接来查语法 - **评论** 参与投票或者分享你的 Markdown 工具推荐 - **关注** 持续更新开发工具技巧一个正在学 AI 的大学生 ‍ **下期预告**《Git 命令大全从入门到高手100 个最常用命令速查2026 版》 --- **相关阅读** - 《GitHub 完全指南从注册到 AI 开发工作流》 - 《Linux 命令大全AI 开发必知的 80 个命令》 **参考资料** - CommonMark Speccommonmark.org - GitHub Flavored Markdown Spec - Markdown Guidemarkdownguide.org