# Markdown ## Markdown介绍 1. Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。 2. Markdown 的设计理念是"易读易写"，让人们能够使用简单的纯文本格式来编写结构化文档。 3. Markdown 编写的文档可以导出 HTML 、Word、图像、PDF、epub 等多种格式的文档。 Markdown 编写的文档后缀为 **.md**, **.markdown**。 ## Markdown 的核心特点包括： **简洁性**：使用直观的符号来表示格式，比如用 `#` 表示标题，用 `*` 表示列表项。这些符号在视觉上就能传达其含义，即使不进行渲染也具有良好的可读性。 **可读性**：即使是纯文本形式的 Markdown 文档，也能清晰地展现文档的结构和层次。读者无需专门的软件就能理解内容的组织方式。 **便携性**：Markdown 文件是纯文本格式，可以在任何文本编辑器中打开和编辑，不依赖特定的软件或操作系统。 **转换性**：可以轻松转换为 HTML、PDF、Word 文档等多种格式，满足不同的发布需求。 方便迁移和备份： ## 轻量级标记语言的概念 标记语言是一种用特定符号来描述文档结构和格式的语言。传统的标记语言如 HTML 功能强大但语法复杂，而轻量级标记语言则简化了这一过程。 与 HTML 相比，Markdown 的优势在于： - 学习成本低，几分钟就能掌握基本语法 - 编写效率高，无需输入复杂的标签 - 专注内容，而非格式细节 - 版本控制友好，便于协作和变更追踪 ## Markdown 与 HTML 的关系 Markdown 并不是 HTML 的替代品，而是 HTML 的简化版本。实际上，Markdown 的最终目标就是转换为 HTML。两者的关系可以这样理解： ``` Markdown 源码 → 解析器 → HTML 输出 → 浏览器渲染 ``` 例如，当你写下： ``` # 这是一个标题 ``` 它会被转换为： ```

这是一个标题

``` 重要的是，在 Markdown 中你可以直接使用 HTML 标签，这为复杂格式提供了灵活性。当 Markdown 的基础语法无法满足需求时，可以嵌入 HTML 代码来实现特定效果。 ## 为什么选择 Markdown **提高写作效率**：无需频繁使用鼠标进行格式设置，可以保持思路的连贯性。写作者可以专注于内容创作，而不被格式问题分散注意力。 **降低学习门槛**：相比于 LaTeX、HTML 等标记语言，Markdown 的语法极其简单，大多数人可以在一小时内掌握基本用法。 **广泛兼容性**：几乎所有的现代文本编辑器、代码编辑器、笔记应用都支持 Markdown。从简单的记事本到专业的 IDE，你都能找到 Markdown 的身影。 **版本控制友好**：由于是纯文本格式，Markdown 文件可以很好地与 Git 等版本控制系统配合，便于追踪文档的修改历史和团队协作。 **未来适应性**：即使特定的软件或平台消失，Markdown 文件作为纯文本仍然可以被访问和编辑，确保了内容的长期可用性。 ## Markdown 的应用场景 ### 技术文档编写 在软件开发领域，Markdown 已成为技术文档的标准格式。它特别适合： - **API 文档**：清晰的标题层次和代码块展示，让 API 说明既专业又易读。许多 API 文档生成工具（如 Swagger）都支持 Markdown 格式的描述。 - **项目说明**：从安装指南到使用手册，Markdown 能够有效组织技术信息。代码示例、配置文件、命令行操作都能得到恰当的展示。 - **开发规范**：团队的编码规范、设计准则、工作流程等都可以用 Markdown 编写，方便团队成员查阅和更新。 ### 博客文章创作 现代的博客平台和静态网站生成器大多支持 Markdown： - **内容管理**：博主可以专注于内容创作，而不必担心复杂的 HTML 编码。文章的格式化通过简单的标记即可完成。 - **平台迁移**：使用 Markdown 编写的文章可以轻松在不同平台间迁移，不会因为平台特有的格式而被锁定。 - **离线编写**：可以在任何文本编辑器中离线编写文章，然后批量发布，提高了写作的灵活性。 ### GitHub README 文件 GitHub 平台广泛使用 Markdown，特别是项目的 README 文件： - **项目介绍**：清晰展示项目的目的、特性、使用方法等关键信息。 - **安装指南**：通过代码块和列表，提供详细的安装和配置步骤。 - **贡献指南**：说明如何参与项目开发，包括代码规范、提交流程等。 - **问题跟踪**：在 Issues 和 Pull Requests 中，开发者使用 Markdown 来描述问题、提供解决方案。 ### 笔记记录和知识管理 Markdown 正成为数字笔记的首选格式： - **学习笔记**：支持数学公式、代码高亮、图表等多种内容类型，适合技术学习和知识整理。 - **会议记录**：清晰的标题结构和列表格式，让会议要点一目了然。 - **知识库建设**：企业和个人都在使用 Markdown 构建知识库，通过链接和标签组织信息。 ### 在线写作平台 越来越多的写作平台开始支持 Markdown： - **GitHub、简书、知乎**：这些平台的编辑器支持 Markdown 语法，让创作者能够快速格式化文章。 - **GitBook、Notion**：专业的文档和笔记平台，原生支持 Markdown，提供强大的组织和协作功能。 - **静态博客生成器**：Jekyll、Hugo、Hexo 等工具让用户能够用 Markdown 创建专业的网站。 **** # 一般过程 >1.使用文本编辑器或 Markdown 专用的应用程序创建 Markdown 文件。该文件应带有 .md 或 .markdown 扩展名. >2.在 Markdown 应用程序中打开 Markdown 文件。 > 3.使用 Markdown 应用程序将 Markdown 文件转换为 HTML 文档。 > 4.在 web 浏览器中查看 HTML 文件，或使用 Markdown 应用程序将其转换为其他文件格式，例如 PDF
# Markdown标题 ## 1、使用=和-标记一级和二级标题 >格式如下 > >``` >我展示的是一级标题 >================= >我展示的是二级标题 >---------------- >``` > >效果如下 > >我展示的是一级标题 >================ > >我展示的是一级标题 >--------------- ## 2、使用#号标记 使用 # 号可表示 1-6 级标题，一级标题对应一个 # 号，二级标题对应两个 # 号，以此类推。 >``` ># 一级标题 >## 二级标题 >### 三级标题 >#### 四级标题 >##### 五级标题 >###### 六级标题 >``` 效果如下 > ># 一级标题 > >## 二级标题 > >### 三级标题 > >#### 四级标题 > >##### 五级标题 > >###### 六级标题 **重要注意事项**： *符号与文字间的空格*：`#` 号和标题文字之间必须有一个空格。这是标准的 Markdown 语法要求。 ``` # 正确写法 #错误写法 ``` *行首位置*：`#` 号必须在行首，前面不能有其他字符（空格或制表符）。 *唯一的一级标题*：在一个文档中，通常只使用一个一级标题作为文档的主标题，这符合良好的文档结构规范。 **标题锚点**： 大多数 Markdown 处理器会自动为标题创建锚点（anchor），便于页面内跳转： ``` [跳转到方法论部分](#方法论) ``` [跳转到方法论部分](#方法论) **标题长度建议**： - 保持标题简洁明了，一般不超过 10 个汉字或 20 个英文字符 - 使用描述性词语，避免模糊的标题如"其他"、"杂项" - 可以使用冒号来分隔主题和副主题 # Markdown文本格式 ## 段落和换行 >Markdown段落没有特殊的格式，直接编写文字就好，段落的换行是使用两个以上空格加上回车. > >``` >abc >def 空一格的情况(并不会换行) >``` > >abc >def > >``` >abc >def 空两格的情况 >``` > >abc >def >或者 > >``` >abc > >def 中间空一行 >``` > >abc > >def > >注意中间空了一行！ > >``` >>abc >def 注意到def前也并非需要'>',在markdown渲染中它依然保持和abc一样的引用块中 >``` > >abc >def >

### 段落的创建方法 在 Markdown 中，段落是文本的基本单位，理解段落规则对于正确格式化文档至关重要。 ### 段落基本规则 - 段落由一个或多个连续的文本行组成 - 段落之间由一个或多个空行分隔 - 普通段落不应该用空格或制表符缩进 **正确的段落写法**： ``` 这是第一个段落。它可以包含多个句子，内容可以很长，会自动换行显示。 这是第二个段落。注意上面有一个空行分隔。 这是第三个段落。 ``` 这是第一个段落。它可以包含多个句子，内容可以很长，会自动换行显示。 这是第二个段落。注意上面有一个空行分隔。 这是第三个段落。 ``` 这是第一段 这是第二段（错误：没有空行分隔） 这是缩进段落（错误：不应该缩进） ``` 这是第一段 这是第二段（错误：没有空行分隔） 这是缩进段落（错误：不应该缩进） ### Typora的渲染问题 许多现代化的 Markdown 编辑器（如 **Typora**）和平台已经考虑到了中文用户的习惯。它们会在渲染时，**自动为中文段落添加首行缩进**。在这种情况下，你什么都不需要做，正常用空行分隔段落即可，编辑器会帮你完成美化。 Typora会自动地给我加上一个空行， 我不知道为什么 ``` abc abc ``` 会变成 abc abc 而 ``` abc abc ``` 会变成 abc abc 而 ``` abc abc ``` 会变成 abc abc ``` abc abc ``` 会变成 abc abc 结论是，当有第二行空行，第三行TAB键的时候，会形成代码块 反而直接写在第二行，会当普通文本. ```   这是使用HTML实体实现的首行缩进。这样写既符合中文排版习惯，又不会被Markdown误认为是代码块。渲染工具会正确地将` `显示为空格。 ```   这是使用HTML实体实现的首行缩进。这样写既符合中文排版习惯，又不会被Markdown误认为是代码块。渲染工具会正确地将` `显示为空格。 ### 强制换行技巧 有时需要在不创建新段落的情况下换行，Markdown 提供了几种方法： **方法一：行尾两个空格** 在行尾添加两个或更多空格，然后按回车： ``` 第一行内容（这里有两个空格） 第二行内容 ``` 第一行内容（这里有两个空格） 第二行内容 **方法二：HTML 换行标签** ``` 第一行内容
第二行内容 ``` 第一行内容
第二行内容 **方法三：反斜杠（部分解析器支持）** ``` 第一行内容\ 第二行内容 ``` 第一行内容\ 第二行内容 ### 空行的作用 空行在 Markdown 中扮演重要角色： **分隔段落**、**分隔不同元素** **最佳实践建议**： - 在标题和内容之间留空行 - 在列表前后留空行 - 在代码块前后留空行 - 保持一致的空行使用习惯 ## 字体 文本强调是写作中的重要技巧，Markdown 提供了简洁的方式来实现粗体和斜体效果。 Markdown 可以使用以下几种字体：粗体和斜体。 **粗体语法：**使用两个星号 ***\*** 或两个下划线 **__** 包围文字 **斜体语法：**使用一个星号 ***** 或一个下划线 **_** 包围文字 **粗斜体组合：**使用三个星号 ***\**** 或三个下划线 **___**。 >``` >*斜体文本* >_斜体文本_ >**粗体文本** >__粗体文本__ >***粗斜体文本*** >___粗斜体文本___ >``` > >*斜体文本* >*斜体文本* >**粗体文本** >**粗体文本** >***粗斜体文本*** >***粗斜体文本*** **使用建议**： - 推荐使用星号 `*` 而不是下划线 `_`，因为星号在各种 Markdown 解析器中兼容性更好 - 不要过度使用强调，重点突出才有效果 - 在中英文混合时，建议在强调符号前后加空格以提高可读性 ## 分割线 >你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线： > >``` >*** >* * * >***** >- - - >---------- >``` > >*** >* * * >***** >- - - >---------- ## 删除线 >如果段落上的文字要添加删除线，只需要在文字的两端加上两个波浪线 ~~ 即可，实例如下: >`~~abc~~` >~~abc~~ ## 下划线 >下划线可以通过 HTML 的 `` 标签来实现： >`带下划线文本` >带下划线文本 >或者 >`__带下划线文本__` >**带下划线文本** ## 脚注 >脚注是对文本的补充说明。 >Markdown 脚注的格式如下: >`[^要注明的文本]` > >``` >创建脚注格式类似这样 [^RUNOOB]. >[^RUNOOB]: 菜鸟教程 -- 学的不仅是技术，更是梦想！！ >``` > >创建脚注格式类似这样 [^RUNOOB]. >[^RUNOOB]:菜鸟教程 -- 学的不仅是技术，更是梦想！！ ## 文本高亮（扩展语法） 文本高亮不是标准 Markdown 语法，但许多扩展支持： **常见语法**（部分平台支持）： ``` 这是==高亮文本== ``` 这是==高亮文本== **HTML 替代方案**： ``` 这是高亮文本 ``` 这是高亮文本 # 列表 >Markdown 支持有序列表和无序列表。 ## 无序列表 >无序列表使用星号(*)、加号(+)或是减号(-)作为列表标记，这些标记后面要添加一个空格，然后再填写内容： >``` >* 第一项 >* 第二项 >* 第三项 > >+ 第一项 >+ 第二项 >+ 第三项 > >- 第一项 >- 第二项 >- 第三项 >``` > > >* 第一项 >* 第二项 >* 第三项 > >* 第一项 >* 第二项 >* 第三项 > > >* 第一项 >* 第二项 >* 第三项 > **选择建议：** - 建议统一使用减号**-**，因为它在视觉上更清晰 - 在同一文档中保持一致的标记方式 - 标记符号后必须有一个空格 有序列表使用数字并加上 . 号来表示，如： >``` >1. 第一项 >2. 第二项 >3. 第三项 >``` > >1. 第一项 >2. 第二项 >3. 第三项 > 从指定数字开始： ```markdown 5. 第五项 6. 第六项 7. 第七项 ``` 5. 第五项 6. 第六项 7. 第七项 ## 列表嵌套 >列表嵌套只需在子列表中的选项前面添加两个或四个空格即可： > >``` >1. 第一项： > - 第一项嵌套的第一个元素 > - 第一项嵌套的第二个元素 >2. 第二项： > - 第二项嵌套的第一个元素 > - 第二项嵌套的第二个元素 >``` 1. 第一项： * 第一项嵌套的第一个元素 * 第一项嵌套的第二个元素 2. 第二项： * 第二项嵌套的第一个元素 * 第二项嵌套的第二个元素 >- 在typora中，好像得要四格作为缩进才能使得作为子列表，否则是父列表并列 >- 输入 `1. 第一项` 后按 `Enter`。 >- 按 `Tab` 键，Typora 会自动将项目符号从数字变为圆点（表示无序子列表）并缩进。 >- 输入 `子项一` 后按 `Enter`。 >- 自动生成下一个子项 `*`，输入 `子项二`。 >- 按 `Enter` 后，再按 `Shift + Tab`，即可退出子列表层级，回到主列表继续输入 `2. 第二项`。 ## 任务列表（复选框列表） 任务列表是 GitHub 风格 Markdown 的扩展功能，现在被广泛支持： **基本语法**： ```markdown - [ ] 未完成的任务 - [x] 已完成的任务 - [ ] 另一个未完成的任务 ``` - [ ] 未完成的任务 - [x] 已完成的任务 - [ ] 另一个未完成的任务 **使用技巧**： - 方括号内的空格和 x 很重要：`[ ]`和`[x]` - 可以与嵌套列表结合使用 - 在项目管理、学习计划、生活清单中特别有用 - 某些编辑器支持点击复选框来切换状态 >注意，typora使得在编辑模式而不是源代码模式，按下enter键，便是源代码两个enter键，得以进行换行； >而编辑模式下，按下一个enter键仅仅只是一个enter键，如果没有第一行末尾两个空格则会被渲染为一行。 > >如果为shift+enter（两次enter），或者按下enter键后回退一格，才会实现列表中的换行（而不是新启一个段落），而并非按下enter键的同次级的列表项。 # Markdown 区块（引用块） >Markdown 区块引用是在段落开头使用 > 符号 ，然后后面紧跟一个空格符号： > >``` >> 区块引用 >> 菜鸟教程 >> 学的不仅是技术更是梦想 >``` > >>区块引用 >>菜鸟教程 >>学的不仅是技术更是梦想 > >另外区块是可以嵌套的，一个 > 符号是最外层，两个 > 符号是第一层嵌套，以此类推： > >``` >最外层 >> 第一层嵌套 >>> 第二层嵌套 >``` > >最外层 >> 第一层嵌套 >>> 第二层嵌套 > ## 区块中使用列表 >区块中使用列表实例如下： >区块中使用列表 > >``` >> 1. 第一项 >> 2. 第二项 >> + 第一项 >> + 第二项 >> + 第三项 >``` > >区块中使用列表 > >1. 第一项 >2. 第二项 > >* 第一项 >* 第二项 >* 第三项 ## 列表中使用区块 >如果要在列表项目内放进区块，那么就需要在`>`前添加四个空格的缩进。 >列表中使用区块实例如下： > >``` >* 第一项 > > 菜鸟教程 > > 学的不仅是技术更是梦想 > * 第二项 > ``` > >* 第一项 > >菜鸟教程 > >学的不仅是技术更是梦想 > * 第二项 # Markdown代码 >`>`的语义是“引用”，而不是“代码块”。Markdown 解析器会根据符号的语义来决定如何渲染内容。 >如果你在代码块前加上 >，解析器会将其解释为“引用” > 区块 用于引用或强调文本，支持嵌套其他 Markdown 语法。 ## 行内代码 代码 用于展示程序代码或命令行指令，内容原样显示，不支持 Markdown 解析。 如果是段落上的一个函数或片段的代码可以用反引号把它包起来（**`**），例如： ```markdown `printf()` 函数 ``` `printf()` >Markdown 代码 >如果是段落上的一个函数或片段的代码可以用反引号把它包起来`` `(`)` ``, 例如： >`` `printf()` 函数 `` >这里使用了双重反引号 [^技巧] >以下还有一种实现打印`` `printf()` 函数 ``的功能 > >利用'\\'进行转义 > >``` markdown >\`printf()\` >```` > >\`printf()\` 函数 ## 代码区块 >代码区块中，一般的 Markdown 语法不会被转换，像是 * 便只是星号，这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。 >代码区块使用 4 个空格或者一个制表符(Tab 键). ### 缩进式代码块 代码区块使用 **4 个空格**或者一个**制表符（Tab 键）**。 语法格式： ``` 正常文本段落 这是缩进式代码块 每行前面有四个空格 保持代码的原始格式 继续正常文本 ``` 正常文本段落 这是缩进式代码块 每行前面有四个空格 保持代码的原始格式 继续正常文本 ### 三反引号代码块 你也可以用 **```** 包裹一段代码，并指定一种语言（也可以不指定）： ~~~markdown ``` 多行代码内容 可以包含空行 保持原有缩进 ``` ~~~ 代码块的高级特性 行号显示 某些 Markdown 渲染器支持显示行号，通过特定的语法或配置实现。 语法示例（部分支持）： ```javascript function fibonacci(n) { if (n <= 1) return n; return fibonacci(n - 1) + fibonacci(n - 2); } console.log(fibonacci(10)); ``` ```javascript const numbers = [1, 2, 3, 4, 5]; const doubled = numbers.map(x => x * 2); const sum = doubled.reduce((a, b) => a + b, 0); console.log(`总和: ${sum}`); ``` ### 总结 - Typora 并不支持单独在编程语言后面加个showLineNumbers或者.line-numbers会添加行号 - **支持**：Typora 通过**全局偏好设置**支持为所有代码块显示行号。 - **如何开启**：`文件` -> `偏好设置` -> `Markdown` -> 勾选 `显示行号`。 - **特性**：此功能是全局的，且在导出时会保留，但它并非标准 Markdown 语法的一部分。 ### 代码差异对比 用于显示代码的添加、删除或修改，常用于展示版本控制中的变更。 **Diff 语法：** ```` ```diff function calculateTotal(items) { - let total = 0; + let total = 0.0; for (let item of items) { - total += item.price; + total += parseFloat(item.price); } + // 保留两位小数 + total = Math.round(total * 100) / 100; return total; } ``` ```` ```diff function calculateTotal(items) { - let total = 0; + let total = 0.0; for (let item of items) { - total += item.price; + total += parseFloat(item.price); } + // 保留两位小数 + total = Math.round(total * 100) / 100; return total; } ``` ```diff @@ -1,5 +1,8 @@ function greetUser(name) { - console.log("Hello " + name); + if (!name) { + throw new Error("Name is required"); + } + console.log(`Hello, ${name}!`); } ``` ```` ```diff @@ -1,5 +1,8 @@ function greetUser(name) { - console.log("Hello " + name); + if (!name) { + throw new Error("Name is required"); + } + console.log(`Hello, ${name}!`); } ``` ```` [^技巧]:使用双引号来包裹单引号，也可以使用`\`来实现