[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"menus-public":3,"blog-10052":83,"blog-10052-comments":92},[4,15,43,66],{"id":5,"title":6,"link":7,"icon":8,"target":9,"sort_order":10,"is_active":11,"parent_id":12,"created_at":13,"children":14},10001,"首页","\u002F","","_blank",0,true,null,"2026-04-04T12:03:45",[],{"id":16,"title":17,"link":18,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":12,"created_at":21,"children":22},10038,"墨言博客","\u002Fblog","_self",1,"2026-10-30T23:08:14",[23,29,36],{"id":24,"title":25,"link":26,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":16,"created_at":27,"children":28},10039,"技术前沿","\u002Fblog?category=10001","2026-10-30T23:10:46",[],{"id":30,"title":31,"link":32,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":16,"created_at":34,"children":35},10042,"生活随笔","\u002Fblog?category=20007",2,"2026-10-30T23:55:19",[],{"id":37,"title":38,"link":39,"icon":8,"target":19,"sort_order":40,"is_active":11,"parent_id":16,"created_at":41,"children":42},10043,"旅游日记","\u002Fblog?category=20006",3,"2026-10-31T00:00:11",[],{"id":33,"title":44,"link":45,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":12,"created_at":46,"children":47},"新闻中心","\u002Fnews","2026-10-24T19:09:40",[48,54,60],{"id":49,"title":50,"link":51,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":33,"created_at":52,"children":53},10046,"产品动态","\u002Fnews?category=20010","2026-10-31T00:17:38",[],{"id":55,"title":56,"link":57,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":33,"created_at":58,"children":59},10047,"新闻热点","\u002Fnews?category=20009","2026-10-31T00:17:55",[],{"id":61,"title":62,"link":63,"icon":8,"target":19,"sort_order":40,"is_active":11,"parent_id":33,"created_at":64,"children":65},10045,"公司动态","\u002Fnews?category=20008","2026-10-31T00:17:11",[],{"id":67,"title":68,"link":69,"icon":8,"target":19,"sort_order":67,"is_active":11,"parent_id":12,"created_at":46,"children":70},4,"精彩视频","\u002Fvideo",[71,77],{"id":72,"title":73,"link":74,"icon":8,"target":19,"sort_order":10,"is_active":11,"parent_id":67,"created_at":75,"children":76},13,"活动记录","\u002Fvideo?category=6","2026-10-25T21:04:39",[],{"id":78,"title":79,"link":80,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":67,"created_at":81,"children":82},11,"产品展示","\u002Fvideo?category=5","2026-10-25T21:02:59",[],{"id":84,"category_id":5,"title":85,"author":8,"summary":86,"cover":87,"content":88,"tags":8,"seo_title":8,"seo_description":8,"seo_keywords":8,"og_image":8,"views":89,"comment_count":10,"is_top":90,"is_published":11,"created_at":91},10052,"Markdown 使用教程","面向初学者与日常写作者的 Markdown 语法手册。涵盖基础语法、扩展语法、Obsidian 专用写法以及常见问题排查。","\u002Fstatic\u002Fuploads\u002Fblogs\u002F1792592834478-663915515.jpg","# Markdown 使用教程\n\n> 面向初学者与日常写作者的 Markdown 语法手册。\n> 涵盖基础语法、扩展语法、Obsidian 专用写法以及常见问题排查。\n\n---\n\n## 目录\n\n- [[#1.Markdown简介|1.Markdown简介]]\n- [[#2.工具与环境|2. 工具与环境]]\n- [[#3.基础语法|3. 基础语法]]\n  - [[#3.1标题|3.1 标题]]\n  - [[#3.2段落与换行|3.2 段落与换行]]\n  - [[#3.3强调|3.3 强调]]\n  - [[#3.4分隔线|3.4 分隔线]]\n- [[#4.列表|4. 列表]]\n  - [[#4.1无序列表|4.1 无序列表]]\n  - [[#4.2有序列表|4.2 有序列表]]\n  - [[#4.3嵌套列表|4.3 嵌套列表]]\n  - [[#4.4任务列表|4.4 任务列表]]\n- [[#5.链接与图片|5. 链接与图片]]\n  - [[#5.1行内链接|5.1 行内链接]]\n  - [[#5.2自动链接|5.2 自动链接]]\n  - [[#5.3引用式链接|5.3 引用式链接]]\n  - [[#5.4图片|5.4 图片]]\n- [[#6.引用|6. 引用]]\n- [[#7.代码|7. 代码]]\n  - [[#7.1行内代码|7.1 行内代码]]\n  - [[#7.2代码块|7.2 代码块]]\n  - [[#7.3代码块中显示反引号|7.3 代码块中显示反引号]]\n- [[#8.表格|8. 表格]]\n  - [[#8.1基本语法|8.1 基本语法]]\n  - [[#8.2对齐方式|8.2 对齐方式]]\n  - [[#8.3单元格内的特殊内容|8.3 单元格内的特殊内容]]\n- [[#9.扩展语法|9. 扩展语法]]\n  - [[#9.1删除线|9.1 删除线]]\n  - [[#9.2脚注|9.2 脚注]]\n  - [[#9.3上下标|9.3 上下标]]\n  - [[#9.4数学公式|9.4 数学公式]]\n  - [[#9.5Mermaid图表|9.5 Mermaid 图表]]\n  - [[#9.6HTML混排|9.6 HTML 混排]]\n  - [[#9.7目录TOC|9.7 目录 TOC]]\n- [[#10.转义字符|10. 转义字符]]\n- [[#11.Obsidian专用语法|11. Obsidian 专用语法]]\n  - [[#11.1双向链接|11.1 双向链接]]\n  - [[#11.2标题锚点|11.2 标题锚点]]\n  - [[#11.3块引用与嵌入|11.3 块引用与嵌入]]\n  - [[#11.4标签|11.4 标签]]\n  - [[#11.5Callout提示块|11.5 Callout 提示块]]\n  - [[#11.6YAML属性|11.6 YAML 属性]]\n- [[#12.实战模板|12. 实战模板]]\n  - [[#12.1README模板|12.1 README 模板]]\n  - [[#12.2技术笔记模板|12.2 技术笔记模板]]\n- [[#13.语法速查表|13. 语法速查表]]\n- [[#14.常见问题|14. 常见问题]]\n\n---\n\n## 1.Markdown简介\n\nMarkdown 是一种**轻量级标记语言**，由 John Gruber 在 2004 年创建。它用纯文本加少量符号来表达格式，文件是 `.md` 后缀，任何文本编辑器都能打开。\n\n它的核心特点：\n\n- **纯文本**：不依赖特定软件，几十年后依然可读\n- **易读易写**：源文件本身就接近排版后的样子\n- **可转换**：能转成 HTML、PDF、Word、幻灯片等格式\n- **版本友好**：适合 Git 管理，便于对比差异\n\n常见的使用场景：\n\n| 场景 | 说明 |\n| --- | --- |\n| 个人笔记 | Obsidian、Typora 等本地笔记工具 |\n| 项目文档 | README、CHANGELOG、接口文档 |\n| 博客写作 | 静态站点生成器（Hexo、Hugo） |\n| 协作平台 | GitHub、GitLab、语雀、飞书文档 |\n| 技术出版 | 电子书、课程讲义、幻灯片 |\n\n### 1.1方言说明\n\nMarkdown 没有唯一标准，常见方言有：\n\n| 方言                             | 特点                           |\n| ------------------------------ | ---------------------------- |\n| CommonMark                     | 最严格的通用规范，多数解析器兼容             |\n| GFM (GitHub Flavored Markdown) | 增加表格、任务列表、删除线、自动链接           |\n| Obsidian Flavored Markdown     | 在 GFM 基础上增加双链、块引用、Callout、公式 |\n\n> 📌 本文以 **GFM + Obsidian** 两种环境都能正常渲染为目标编写。遇到平台差异时会单独标注。\n\n---\n\n## 2.工具与环境\n\n| 工具              | 平台                        | 特点                  |\n| --------------- | ------------------------- | ------------------- |\n| Obsidian        | Win \u002F macOS \u002F Linux \u002F 移动端 | 本地优先，双链与图谱强大，适合知识库  |\n| Typora          | Win \u002F macOS \u002F Linux       | 所见即所得，写作体验流畅        |\n| VS Code         | 全平台                       | 配合插件可预览、可导出，适合写代码文档 |\n| GitHub \u002F GitLab | 网页                        | 仓库内自动渲染 README 与文档  |\n| 语雀 \u002F 飞书         | 网页                        | 团队协作，支持大部分 GFM 语法   |\n\n写文件时的三个基本要求：\n\n1. 文件后缀用 `.md`（少数平台也认 `.markdown`）\n2. 编码统一使用 **UTF-8**，避免中文乱码\n3. 段落之间留**一个空行**，这是 Markdown 最重要的排版习惯\n\n---\n\n## 3.基础语法\n\n### 3.1标题\n\n用 `#` 表示标题，一级标题 1 个 `#`，最多到六级：\n\n```markdown\n# 一级标题\n## 二级标题\n### 三级标题\n#### 四级标题\n##### 五级标题\n###### 六级标题\n```\n\n各级标题的层级关系：\n\n| 写法         | 层级    | 典型用途        |\n| ---------- | ----- | ----------- |\n| `#`        | 一级    | 文章标题，全文只用一个 |\n| `##`       | 二级    | 主要章节        |\n| `###`      | 三级    | 章节下的小节      |\n| `####` 及以下 | 四级至六级 | 更细的划分，尽量少用  |\n\n要点：\n\n- `#` 后面建议加一个空格，兼容性最好\n- 一篇文章通常只用一个一级标题（文章标题）\n- 不要跳级使用（比如从 `##` 直接到 `####`），方便生成目录\n\n另一种写法是 Setext 风格（仅支持一到二级），用下划线表示：\n\n```markdown\n一级标题\n========\n\n二级标题\n--------\n```\n\n> ⚠️ 这种写法容易和分隔线、列表混淆，日常不推荐。\n\n### 3.2段落与换行\n\n**段落**：连续的文字算一段，段落之间用**空行**分隔。直接回车换行在多数渲染器里会被合并成同一段。\n\n```markdown\n这是第一段。\n这行仍然属于第一段。\n\n这是第二段。\n```\n\n**段内换行**有三种方式：\n\n| 方式        | 写法          | 说明                    |\n| --------- | ----------- | --------------------- |\n| 行尾两个空格    | `文字␣␣` + 回车 | 最通用，但空格看不见            |\n| 行尾反斜杠     | `文字\\` + 回车  | 直观，GFM 支持             |\n| HTML 换行标签 | `\u003Cbr>`      | 兼容性最好，但不够“纯 Markdown” |\n\n```markdown\n第一行结尾加两个空格  \n第二行\n```\n\n### 3.3强调\n\n```markdown\n*斜体* 或 _斜体_\n**粗体** 或 __粗体__\n***粗斜体***\n~~删除线~~\n```\n\n效果：*斜体*、**粗体**、***粗斜体***、~~删除线~~\n\n注意：\n\n- 强调符号**紧贴文字**，不要写成 `* 斜体 *`\n- 中文里用 `_` 容易在词中间失效，推荐统一用 `*`\n- 删除线属于 GFM 扩展，极少数老解析器不支持\n\n### 3.4分隔线\n\n单独一行写三个或更多的 `-`、`*`、`_`：\n\n```markdown\n---\n\n***\n\n___\n```\n\n效果：\n\n---\n\n要点：分隔线**前后各留一个空行**，否则可能被当成二级标题（Setext）或列表的一部分。\n\n---\n\n## 4.列表\n\n### 4.1无序列表\n\n用 `-`、`*`、`+` 开头，后面跟一个空格：\n\n```markdown\n- 苹果\n- 香蕉\n- 橙子\n```\n\n效果：\n\n- 苹果\n- 香蕉\n- 橙子\n\n> 📌 同一篇文档里**统一用一种符号**，混用虽然能渲染，但不利于后续维护。\n\n### 4.2有序列表\n\n用数字加点开头：\n\n```markdown\n1. 准备食材\n2. 处理食材\n3. 下锅烹饪\n```\n\n效果：\n\n1. 准备食材\n2. 处理食材\n3. 下锅烹饪\n\n关键点：**后续编号写什么数字都不影响渲染**，解析器会自动按顺序编号。所以下面这种写法渲染结果和上面完全一样：\n\n```markdown\n1. 准备食材\n1. 处理食材\n1. 下锅烹饪\n```\n\n这种写法在增删条目时不用重新编号，是被广泛推荐的写法。但如果你需要**从指定数字开始**（比如从 3 开始），就必须显式写第一个数字：\n\n```markdown\n3. 第三步\n4. 第四步\n```\n\n### 4.3嵌套列表\n\n子列表用 **2 个或 4 个空格**缩进（推荐 4 个空格或与父级内容对齐的 Tab）：\n\n```markdown\n- 前端\n    - HTML\n    - CSS\n    - JavaScript\n- 后端\n    1. Node.js\n    2. Python\n```\n\n效果：\n\n- 前端\n    - HTML\n    - CSS\n    - JavaScript\n- 后端\n    1. Node.js\n    2. Python\n\n常见坑：缩进不足会被当成同级；缩进过多可能被当成代码块（4 空格缩进在部分解析器里等于代码块，Obsidian 中只要紧跟在列表项后就没问题）。\n\n### 4.4任务列表\n\nGFM 扩展语法，用 `- [ ]` 表示未完成，`- [x]` 表示已完成：\n\n```markdown\n- [x] 完成需求评审\n- [x] 编写接口文档\n- [ ] 联调测试\n- [ ] 上线发布\n```\n\n效果：\n\n- [x] 完成需求评审\n- [x] 编写接口文档\n- [ ] 联调测试\n- [ ] 上线发布\n\n在 Obsidian 里点击方框即可切换状态，是管理待办最轻量的方式。\n\n---\n\n## 5.链接与图片\n\n### 5.1行内链接\n\n```markdown\n[显示文字](https:\u002F\u002Fexample.com)\n[带标题的链接](https:\u002F\u002Fexample.com \"鼠标悬停显示的文字\")\n```\n\n效果：[显示文字](https:\u002F\u002Fexample.com)\n\n指向本文其他位置的写法见 [[#11.2标题锚点|11.2 标题锚点]]。\n\n### 5.2自动链接\n\n尖括号包裹网址或邮箱，会直接变成可点击链接：\n\n```markdown\n\u003Chttps:\u002F\u002Fexample.com>\n\u003Csomeone@example.com>\n```\n\n效果：\u003Chttps:\u002F\u002Fexample.com>\n\nGFM 还支持裸网址自动识别，如 `https:\u002F\u002Fexample.com` 直接写成文本也能点击。但中文语境下裸链接容易和标点粘连，推荐仍用尖括号。\n\n### 5.3引用式链接\n\n把网址集中放在文末，正文只写引用标识，适合长文或同一链接多次出现：\n\n```markdown\n这是[官方文档][docs]的地址，也可以看[入门指南][docs]。\n\n[docs]: https:\u002F\u002Fexample.com\u002Fdocs \"官方文档\"\n```\n\n效果：这是[官方文档][docs]的地址。\n\n[docs]: https:\u002F\u002Fexample.com\u002Fdocs \"官方文档\"\n\n### 5.4图片\n\n语法只比链接多一个感叹号：\n\n```markdown\n![图片描述](https:\u002F\u002Fexample.com\u002Fpic.png)\n![图片描述](.\u002Fimages\u002Fpic.png \"图片标题\")\n```\n\n要点：\n\n- `图片描述` 是**替代文本**，图片加载失败时显示，也利于无障碍阅读\n- 路径支持相对路径、绝对路径、网络地址\n- Obsidian 中更常用 `![[图片名.png]]`，见 [[#11.3块引用与嵌入|11.3 块引用与嵌入]]\n\n调整图片尺寸（GitHub 与部分平台支持 HTML 写法）：\n\n```html\n\u003Cimg src=\".\u002Fimages\u002Fpic.png\" width=\"300\" alt=\"示意图\">\n```\n\n---\n\n## 6.引用\n\n用 `>` 开头表示引用块：\n\n```markdown\n> 这是一段引用。\n> 引用可以有多行。\n>\n> 空一行后仍在同一个引用块内。\n```\n\n效果：\n\n> 这是一段引用。\n> 引用可以有多行。\n>\n> 空一行后仍在同一个引用块内。\n\n引用可以嵌套，也可以容纳列表、代码等块级内容：\n\n````markdown\n> 外层引用\n> > 嵌套引用\n>\n> - 引用中的列表\n> - 第二项\n>\n> ```js\n> console.log(\"引用中的代码\");\n> ```\n````\n\n要点：\n\n- 每行都要以 `>` 开头，空行也要写 `>`（或留空但保持缩进）\n- 引用内的 Markdown 语法照常生效\n\n---\n\n## 7.代码\n\n### 7.1行内代码\n\n用一对反引号包裹：\n\n```markdown\n使用 `npm install` 安装依赖。\n```\n\n效果：使用 `npm install` 安装依赖。\n\n如果代码本身包含反引号，用双反引号包裹：\n\n```markdown\n``代码里有 `反引号` 的情况``\n```\n\n### 7.2代码块\n\n用三个反引号包裹，并在开头标注语言以启用高亮：\n\n````markdown\n```javascript\nfunction greet(name) {\n  console.log(`Hello, ${name}`);\n}\n```\n````\n\n效果：\n\n```javascript\nfunction greet(name) {\n  console.log(`Hello, ${name}`);\n}\n```\n\n常用语言标注：\n\n| 标注 | 语言 | 标注 | 语言 |\n| --- | --- | --- | --- |\n| `bash` \u002F `shell` | Shell | `js` \u002F `javascript` | JavaScript |\n| `python` | Python | `ts` \u002F `typescript` | TypeScript |\n| `json` | JSON | `yaml` \u002F `yml` | YAML |\n| `html` | HTML | `css` | CSS |\n| `sql` | SQL | `markdown` \u002F `md` | Markdown |\n| `java` | Java | `go` | Go |\n| `c` \u002F `cpp` | C \u002F C++ | `diff` | 差异对比 |\n\n不写语言标注也能渲染成代码块，但没有高亮。\n\n### 7.3代码块中显示反引号\n\n如果代码块内部本身包含三个反引号（比如你要教别人写代码块），外层要用**四个**反引号：\n\n``````markdown\n````markdown\n```bash\necho \"hello\"\n```\n````\n``````\n\n规则很简单：**外层反引号数量 > 内层最多连续反引号数量**。\n\n---\n\n## 8.表格\n\n### 8.1基本语法\n\n用 `|` 分隔单元格，第二行用 `-` 定义表头分隔线：\n\n```markdown\n| 姓名 | 年龄 | 城市 |\n| --- | --- | --- |\n| 张三 | 25 | 北京 |\n| 李四 | 30 | 上海 |\n```\n\n效果：\n\n| 姓名 | 年龄 | 城市 |\n| --- | --- | --- |\n| 张三 | 25 | 北京 |\n| 李四 | 30 | 上海 |\n\n要点：\n\n- 表格**前后必须有空行**，否则不会渲染（最常见的报错原因）\n- 第二行的分隔线不能省略\n- 列数不必对齐，源文件丑一点不影响渲染\n\n### 8.2对齐方式\n\n在分隔线中加入冒号控制对齐：\n\n```markdown\n| 左对齐 | 居中 | 右对齐 |\n| :--- | :---: | ---: |\n| A | B | C |\n```\n\n效果：\n\n| 左对齐 | 居中 | 右对齐 |\n| :--- | :---: | ---: |\n| A | B | C |\n\n### 8.3单元格内的特殊内容\n\n**竖线转义**：单元格内容里要写 `|`，用 `\\|`：\n\n```markdown\n| 运算符 | 含义 |\n| --- | --- |\n| `a \\| b` | 按位或 |\n```\n\n**单元格内换行**：标准 Markdown 不支持，只能用 `\u003Cbr>`：\n\n```markdown\n| 项目 | 说明 |\n| --- | --- |\n| 安装 | 第一步\u003Cbr>第二步 |\n```\n\n**单元格内写代码**：用反引号，但如果代码里同时有竖线，需要同时处理转义。\n\n---\n\n## 9.扩展语法\n\n以下语法属于扩展，GFM 或 Obsidian 支持，但并非所有平台都认，跨平台发布时需注意。\n\n### 9.1删除线\n\n```markdown\n~~这段文字已作废~~\n```\n\n效果：~~这段文字已作废~~\n\n### 9.2脚注\n\n```markdown\nMarkdown 由 John Gruber 创建[^1]。\n\n[^1]: 官方站点：https:\u002F\u002Fdaringfireball.net\u002Fprojects\u002Fmarkdown\u002F\n```\n\n效果：Markdown 由 John Gruber 创建[^1]。\n\n[^1]: 官方站点：https:\u002F\u002Fdaringfireball.net\u002Fprojects\u002Fmarkdown\u002F\n\n### 9.3上下标\n\n标准 Markdown 没有上下标，用 HTML 标签实现：\n\n```markdown\nH\u003Csub>2\u003C\u002Fsub>O\nx\u003Csup>2\u003C\u002Fsup>\n```\n\n效果：H\u003Csub>2\u003C\u002Fsub>O、x\u003Csup>2\u003C\u002Fsup>\n\n### 9.4数学公式\n\nObsidian、Typora、GitHub 均支持 LaTeX 公式。行内用 `$...$`，独立成块用 `$$...$$`：\n\n```markdown\n质能方程：$E = mc^2$\n\n$$\n\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}\n$$\n```\n\n效果：\n\n质能方程：$E = mc^2$\n\n$$\n\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}\n$$\n\n注意：`$` 与公式之间不要留空格，中文环境里 `$` 也可能触发意外解析，必要时用 `\\$` 转义。\n\n### 9.5Mermaid图表\n\nObsidian、GitHub、Typora 支持用代码块直接画图：\n\n````markdown\n```mermaid\ngraph TD\n    A[开始] --> B{条件判断}\n    B -->|是| C[执行操作]\n    B -->|否| D[结束]\n    C --> D\n```\n````\n\n效果：\n\n```mermaid\ngraph TD\n    A[开始] --> B{条件判断}\n    B -->|是| C[执行操作]\n    B -->|否| D[结束]\n    C --> D\n```\n\n除了流程图（`graph` \u002F `flowchart`），还支持时序图（`sequenceDiagram`）、甘特图（`gantt`）、类图（`classDiagram`）、饼图（`pie`）等。\n\n### 9.6HTML混排\n\nMarkdown 允许直接嵌入 HTML，用于实现 Markdown 做不到的效果：\n\n```html\n\u003Cdetails>\n\u003Csummary>点击展开\u003C\u002Fsummary>\n\n这里是被折叠的内容。\n\n\u003C\u002Fdetails>\n```\n\n效果：\n\n\u003Cdetails>\n\u003Csummary>点击展开\u003C\u002Fsummary>\n\n这里是被折叠的内容。\n\n\u003C\u002Fdetails>\n\n要点：\n\n- `\u003Cdetails>` 内部**前后要留空行**，否则内部 Markdown 不解析\n- 出于安全考虑，GitHub 会过滤 `script`、`style` 等标签\n- 不要滥用 HTML，会破坏纯文本可读性\n\n### 9.7目录TOC\n\nGitHub 会自动为标题生成锚点，但**不会自动生成目录**，需要手动写或借助工具。常见写法：\n\n```markdown\n- [第一节](#第一节)\n- [第二节](#第二节)\n```\n\n锚点规则各平台不同，是最容易踩坑的地方：\n\n| 平台 | 锚点规则 | 示例（标题 `## 1. 环境要求`） |\n| --- | --- | --- |\n| GitHub | 转小写、去标点、空格转 `-` | `#1-环境要求` |\n| Obsidian | 标题原文，保留标点与空格 | `#1. 环境要求` |\n\n> ⚠️ 在 Obsidian 中必须使用双链格式 `[[#标题原文|显示文字]]`，用 GitHub 风格锚点会跳转失败。详见 [[#11.2标题锚点|11.2 标题锚点]]。\n\n---\n\n## 10.转义字符\n\n在 Markdown 中有特殊含义的符号，前面加反斜杠 `\\` 可以按字面显示：\n\n```markdown\n\\*不是斜体\\*\n\\# 不是标题\n\\[不是链接\\]\n1\\. 不是列表\n```\n\n可转义的字符包括：\n\n`\\` `` ` `` `*` `_` `{` `}` `[` `]` `(` `)` `#` `+` `-` `.` `!` `|` `>` `~`\n\n常见使用场景：\n\n- 写 `C++`、`C#` 这类词时通常无需转义，但如果出现在行首要注意\n- 表格单元格内写竖线用 `\\|`\n- 行首写 `2024.` 这类年份时可能被识别成有序列表，写成 `2024\\.`\n\n---\n\n## 11.Obsidian专用语法\n\nObsidian 在 GFM 基础上扩展了一套“知识库”语法，是本目录文档的主要查看环境。\n\n### 11.1双向链接\n\n用双方括号引用库内其他笔记：\n\n```markdown\n[[另一篇笔记]]\n[[另一篇笔记|显示为别的文字]]\n[[另一篇笔记#某个标题]]\n```\n\n要点：\n\n- 链接的是**文件名**（不含 `.md` 后缀）\n- 文件名重复时要写路径，如 `[[文件夹\u002F笔记名]]`\n- 被链接的笔记会自动出现在“反向链接”面板中\n\n### 11.2标题锚点\n\n跳转到本文某个标题，可写 `[[#标题]]` 或 `[[#标题|显示文字]]`：\n\n```markdown\n[[#3.2段落与换行|段落与换行]]\n[[#11.Obsidian专用语法]]\n```\n\n**关键规则**：锚点必须是标题 `##` 之后的**原文**，不能按 GitHub 规则转换。\n\n| 标题写法 | 正确锚点 | 错误锚点 |\n| --- | --- | --- |\n| `## 1.Markdown简介` | `[[#1.Markdown简介]]` | `[[#1-markdown简介]]` |\n| `## 3.2段落与换行` | `[[#3.2段落与换行]]` | `[[#32段落与换行]]` |\n| `## 六、Docker命令` | `[[#六、Docker命令]]` | `[[#六docker命令]]` |\n\n> ⚠️ **标题中不要出现 ASCII 空格**。Obsidian 的 `[[#锚点|别名]]` 遇到标题里的空格时容易解析失败。推荐写成 `## 3.2段落与换行` 这种连写形式，并在链接里用别名显示成 `3.2 段落与换行`。\n>\n> 本文所有标题均已按此规则处理，可直接作为模板参考。\n\n### 11.3块引用与嵌入\n\n**块引用**：在某个段落末尾写 `^块标识`，就可以从别处精确引用这一段：\n\n```markdown\n这句话很重要，需要被引用。 ^important-note\n```\n\n然后在其他笔记里引用：\n\n```markdown\n[[笔记名#^important-note]]\n```\n\n**嵌入**：链接前加感叹号，把内容直接显示出来：\n\n```markdown\n![[另一篇笔记]]                嵌入整篇笔记\n![[另一篇笔记#某个标题]]        嵌入某个章节\n![[图片.png]]                  嵌入图片（可加尺寸：![[图片.png|300]]）\n![[文档.pdf]]                  嵌入 PDF\n```\n\n### 11.4标签\n\n用 `#标签` 做横向分类，与文件夹的纵向结构互补：\n\n```markdown\n#项目\u002F进行中\n#技术\u002F前端\u002FReact\n#待整理\n```\n\n要点：\n\n- 标签**不能包含空格**，多层级用 `\u002F` 分隔\n- 与标题冲突：行首的 `#标题` 若后面没有空格可能被识别为标签，写标题时保持 `#` 后有空格\n- 在搜索面板输入 `tag:#项目` 可筛选\n\n### 11.5Callout提示块\n\n用 `> [!类型]` 生成带颜色和图标的高亮块：\n\n```markdown\n> [!note] 说明\n> 这是一条补充说明。\n\n> [!warning] 注意\n> 这里容易出错。\n\n> [!tip]- 可折叠提示\n> 标题带减号表示默认折叠。\n```\n\n支持的常用类型：\n\n| 类型 | 用途 | 类型 | 用途 |\n| --- | --- | --- | --- |\n| `note` | 普通说明 | `tip` | 技巧建议 |\n| `info` | 信息 | `warning` | 警告 |\n| `danger` | 危险操作 | `success` | 成功\u002F完成 |\n| `question` | 疑问 | `quote` | 引用 |\n| `example` | 示例 | `bug` | 缺陷记录 |\n\n可折叠写法：`[!note]-` 默认收起，`[!note]+` 默认展开。\n\n### 11.6YAML属性\n\n文件最顶部用三条横线包裹 YAML，可定义标题、标签、别名等元数据：\n\n```yaml\n---\ntitle: Markdown 使用教程\ntags:\n  - 教程\n  - 写作\naliases:\n  - MD教程\ncreated: 2026-10-21\n---\n```\n\n这些属性会被 Obsidian 的搜索、别名跳转、模板插件读取。注意：\n\n- 必须位于**文件第一行**，前面不能有空行\n- `---` 前后不要缩进\n- 如果文档不需要属性，可以完全不写\n\n---\n\n## 12.实战模板\n\n### 12.1README模板\n\n````markdown\n# 项目名称\n\n一句话说明这个项目是做什么的。\n\n## 功能特性\n\n- 特性一\n- 特性二\n\n## 快速开始\n\n```bash\ngit clone https:\u002F\u002Fexample.com\u002Frepo.git\ncd repo\nnpm install\nnpm run dev\n```\n\n## 配置说明\n\n| 变量 | 说明 | 默认值 |\n| --- | --- | --- |\n| `PORT` | 服务端口 | `3000` |\n\n## 目录结构\n\n```text\nsrc\u002F\n├── components\u002F\n├── pages\u002F\n└── utils\u002F\n```\n\n## 许可证\n\nMIT\n````\n\n### 12.2技术笔记模板\n\n````markdown\n---\ntitle: 主题名称\ntags:\n  - 技术\ncreated: 2026-10-21\n---\n\n# 主题名称\n\n## 背景与问题\n\n为什么要记录这篇笔记。\n\n## 核心结论\n\n> [!tip] 结论先行\n> 用两三句话把最重要的结论写在这里。\n\n## 详细内容\n\n### 原理\n\n### 实践步骤\n\n1. 第一步\n2. 第二步\n\n```bash\n# 可执行的命令\n```\n\n### 踩坑记录\n\n| 现象 | 原因 | 解决 |\n| --- | --- | --- |\n| 报错信息 | 原因分析 | 处理方式 |\n\n## 参考资料\n\n- [官方文档](https:\u002F\u002Fexample.com)\n````\n\n---\n\n## 13.语法速查表\n\n| 想要的效果 | 写法 |\n| --- | --- |\n| 标题 | `# 一级` 到 `###### 六级` |\n| 粗体 | `**文字**` |\n| 斜体 | `*文字*` |\n| 粗斜体 | `***文字***` |\n| 删除线 | `~~文字~~` |\n| 分隔线 | `---` |\n| 无序列表 | `- 项目` |\n| 有序列表 | `1. 项目` |\n| 任务列表 | `- [ ] 待办` \u002F `- [x] 完成` |\n| 行内代码 | `` `code` `` |\n| 代码块 | 三个反引号 + 语言名 |\n| 链接 | `[文字](url)` |\n| 图片 | `![描述](url)` |\n| 引用 | `> 内容` |\n| 表格 | `\\| 表头 \\|` + `\\| --- \\|` |\n| 脚注 | `文字[^1]` + `[^1]: 内容` |\n| 公式 | `$公式$` \u002F `$$公式$$` |\n| 换行 | 行尾两个空格或 `\u003Cbr>` |\n| 转义 | `\\*` |\n| Obsidian双链 | `[[笔记名]]` |\n| 标题锚点 | `[[#标题原文\\|别名]]` |\n| 嵌入 | `![[笔记名]]` |\n| 标签 | `#分类\u002F子类` |\n| 提示块 | `> [!note] 标题` |\n\n---\n\n## 14.常见问题\n\n### 14.1表格不渲染\n\n**原因**：表格前缺少空行，或第二行分隔线写错。\n\n**排查**：确认表格上方有一个空行；确认第二行是 `| --- | --- |` 形式且列数与表头一致。\n\n### 14.2回车换行不生效\n\n**原因**：Markdown 把单个换行视为空格。\n\n**解决**：行尾加两个空格、加 `\\`，或使用 `\u003Cbr>`。段落之间直接空一行最稳。\n\n### 14.3有序列表编号乱掉\n\n**原因**：列表中间插入了空行或非列表内容，导致列表被切断。\n\n**解决**：保持列表连续；需要插入说明文字时，用两个以上空格缩进使其属于列表项。\n\n### 14.4代码块里的内容被解析\n\n**原因**：代码块用反引号包裹，但代码内部含有反引号。\n\n**解决**：外层反引号数量大于内层，例如外层四个反引号包裹内层三个。\n\n### 14.5图片不显示\n\n**原因**：路径错误或大小写不一致。Windows 在资源管理器里不区分大小写，但 GitHub 等平台区分。\n\n**解决**：使用相对路径 `.\u002Fimages\u002Fpic.png`，并核对文件名大小写与扩展名。\n\n### 14.6Obsidian目录点击无反应\n\n**原因**：锚点用了 GitHub 的 slug 规则，或标题中含 ASCII 空格导致链接被截断。\n\n**解决**：锚点改为标题原文，标题尽量去掉空格，并在链接里用别名控制显示效果。\n\n### 14.7中文标点导致链接失效\n\n**原因**：全角括号、全角冒号不能用于语法结构。\n\n**解决**：语法符号一律用半角：`()`、`:`、`|`、`#`；中文标点只能出现在正文里。\n\n### 14.8加粗在中文里不生效\n\n**原因**：强调符号与文字之间有空格，或符号紧贴中文标点。\n\n**解决**：写成 `**加粗文字**`，符号与文字之间不留空格。\n\n---\n\n## 附：写作习惯建议\n\n1. **一屏能读完的段落**：长段落拆短，Markdown 的可读性来自空行与列表\n2. **标题即大纲**：写完先检查标题层级，能直接当目录用\n3. **少用花哨语法**：Callout、折叠块、Mermaid 适度使用，过多会喧宾夺主\n4. **链接用相对路径**：文档随仓库迁移时不至于全部失效\n5. **源文件也要可读**：Markdown 的价值在于即使不渲染也看得懂",21,false,"2026-10-21T22:27:42",{"list":93,"total":10,"page":20,"size":94},[],30]