├── .gitattributes ├── .gitignore ├── LICENSE ├── README.md ├── book.toml └── src ├── README.md ├── SUMMARY.md ├── formula.md ├── html.md ├── imgs ├── blockquotes.png ├── demo-image.png ├── emoji.png └── tasklists.png ├── intro.md ├── syntax-examples.md └── toolchain.md /.gitattributes: -------------------------------------------------------------------------------- 1 | *.md linguist-detectable=true 2 | 3 | * text=auto eol=lf 4 | 5 | *.{cmd,[cC][mM][dD]} text eol=crlf 6 | *.{bat,[bB][aA][tT]} text eol=crlf 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | .idea 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 zzy (ask@rusthub.org) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Markdown 指南 2 | 3 | [Markdown 指南-https://markdown-guide.rusthub.org](https://markdown-guide.rusthub.org)，部分 Markdown 基础语法译自 GitHub 官方 Mastering Markdown 文档。 4 | 5 | 💥 笔者在 GitHub 官方文档基础上补充了未提及的 Markdown 语法、重组了内容结构、将实例中文化、增加了数学公式、Markdown 和 HTML 融合应用，以及 Markdown 工具链等内容。 6 | 7 | > **持续更新**：诸如 Mermaid 关系图、GeoJSON 和 TopoJSON 地图、STL 3D 模型等特性语法和示例，正在更新中…… 8 | 9 | 本文目的为整理 Markdown 知识，希望可以帮助到读者。 10 | 11 | ------ 12 | 13 | ## 声明 14 | 15 | 水平有限，错漏难免。若有指教，请 [发issue到GitHub](https://github.com/piexue/markdown-guide-book-site)，或者直接联系。 16 | 17 | 💥 笔者无意侵犯任何人的权利和利益，故若有不适，请联系我。 18 | 19 | ------ 20 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["zzy"] 3 | title = "Markdown 指南 - Markdown Guide" 4 | description = "markdown guide, markdown 教程, markdown 语法实例, markdown 文档, md 文档" 5 | src = "src" 6 | language = "zh" 7 | multilingual = true 8 | 9 | [rust] 10 | edition = "2021" 11 | 12 | [output.html] 13 | theme = "../../books-theme/theme" 14 | git-repository-url = "https://github.com/zzy" 15 | curly-quotes = true 16 | mathjax-support = true 17 | 18 | [output.html.fold] 19 | enable = true 20 | level = 4 21 | 22 | [output.html.playpen] 23 | editable = true 24 | line-numbers = true 25 | copy-js = true 26 | 27 | [output.html.search] 28 | limit-results = 20 29 | use-boolean-and = true 30 | boost-title = 2 31 | boost-hierarchy = 2 32 | boost-paragraph = 1 33 | expand = true 34 | heading-split-level = 3 35 | copy-js = true 36 | 37 | [output.html.print] 38 | enable = false 39 | -------------------------------------------------------------------------------- /src/README.md: -------------------------------------------------------------------------------- 1 | {{#include ../README.md }} -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # 目录 2 | 3 | - [序言](README.md) 4 | - [Markdown介 绍](intro.md) 5 | - [Markdown 语法和实例](syntax-examples.md) 6 | - [Markdown 数学公式](formula.md) 7 | - [Markdown 和 HTML 融合](html.md) 8 | - [Markdown 工具链](toolchain.md) 9 | -------------------------------------------------------------------------------- /src/formula.md: -------------------------------------------------------------------------------- 1 | # Markdown 数学公式 2 | 3 | Markdown中，支持完整的 `LaTeX` 数学公式语法。 4 | 5 | > *注：* 此章节包含 `LaTeX` 数学公式语法，须通过工具（如 [mdBook](https://mdbook-guide.rusthub.org)、gitBook），或者已嵌 `LaTeX` 公式的编辑器，方可预览或构建（[阅读已构建电子书](https://markdown-guide.rusthub.org/formula.html)）。 6 | 7 | - [公式样式及注释](#公式样式及注释) 8 | - [上标和下标](#上标和下标) 9 | - [上划线与下划线](#上划线与下划线) 10 | - [分数](#分数) 11 | - [方程组](#方程组) 12 | - [大括号](#大括号) 13 | - [开根号](#开根号) 14 | - [希腊字母](#希腊字母) 15 | - [运算符](#运算符) 16 | - [微积分符号](#微积分符号) 17 | - [逻辑符号](#逻辑符号) 18 | - [特殊符号](#特殊符号) 19 | - [使用`HTML`语法表达数学公式](#使用html语法表达数学公式) 20 | 21 | ## 公式样式及注释 22 | 23 | > 数学公式样式的支持程度，取决于你使用的构建工具（如 [mdBook](https://mdbook-guide.rusthub.org)、gitBook）或编辑器。 24 | 25 | - 换行：`\\`、`\\\\` 26 | - 空格：`\`、`\,`、`\;`、`\quad`、`\qquad` 27 | - 居中：用 `$$` 包裹 28 | - 字体样式：加粗（`\mathbf`）、斜体（`\mathit`） 29 | - 字体大小：`\tiny`、`\scriptsize`、`\small`、`\normalsize`、`\large`、`\Large`、`\huge`、`\Huge` 30 | - 颜色：`\color{颜色值}{数/字/符}` 31 | - 注释：`\text{内容}` 32 | 33 | ### 1. 实例代码 34 | 35 | ``` Markdown 36 | $$ 37 | a \ b \\ 38 | a \quad b \\ 39 | a \qquad b \\ 40 | \mathit{a} + \mathbf{b} \\ 41 | X^{2m}_{3n} \\ 42 | \text{注意和下面默认大小对比——} \\ 43 | \tiny X^{2m}_{3n} \\ 44 | \scriptsize X^{2m}_{3n} \\ 45 | \small X^{2m}_{3n} \\ 46 | \normalsize X^{2m}_{3n} \text{（默认大小）} \\ 47 | \large X^{2m}_{3n} \\ 48 | \Large X^{2m}_{3n} \\ 49 | \huge X^{2m}_{3n} \\ 50 | \Huge X^{2m}_{3n} \\ 51 | $$ 52 | ``` 53 | 54 | ### 2. 呈现效果 55 | 56 |
57 | 58 | $$ 59 | a \ b \\\\ 60 | a \quad b \\\\ 61 | a \qquad b \\\\ 62 | \mathit{a} + \mathbf{b} \\\\ 63 | X^{2m}_{3n} \\\\ 64 | \text{注意和下面默认大小对比——} 65 | $$ 66 | 67 | $$ \tiny X^{2m}_{3n} $$ 68 | 69 | $$ \scriptsize X^{2m}_{3n} $$ 70 | 71 | $$ \small X^{2m}_{3n} $$ 72 | 73 | $$ \normalsize X^{2m}_{3n} \text{（默认大小）} $$ 74 | 75 | $$ \large X^{2m}_{3n} $$ 76 | 77 | $$ \Large X^{2m}_{3n} $$ 78 | 79 | $$ \huge X^{2m}_{3n} $$ 80 | 81 | $$ \Huge X^{2m}_{3n} $$ 82 | 83 |
84 | 85 | ## 上标和下标 86 | 87 | - 上标：使用 **`^`** 连接数/字/符和其上标值； 88 | - 下标：使用 **`-`** 连接数/字/符和其下标值； 89 | - 较为复杂的表达式用 `{}` 包含。 90 | 91 | ### 1. 实例代码 92 | 93 | ``` Markdown 94 | 上标：$$ x^2 $$ 95 | 下标：$$ Y_1 $$ 96 | 综合：$$ X^{2m}_{3n} $$ 97 | ``` 98 | 99 | ### 2. 呈现效果 100 | 101 |
102 | 103 | $$ 104 | 上标：x^2 \\\\ 105 | 下标：Y_1 \\\\ 106 | 综合：X^{2m}_{3n} a^g_h 107 | $$ 108 | 109 |
110 | 111 | ## 上划线与下划线 112 | 113 | - 上划线：`\overline{}` 114 | - 下划线：`\underline{}` 115 | 116 | ### 1. 实例代码 117 | 118 | ``` Markdown 119 | 上划线：$$ \overline{x^2+a+b} $$ 120 | 下划线：$$ \underline{Y_1-c-d} $$ 121 | ``` 122 | 123 | ### 2. 呈现效果 124 | 125 |
126 | 127 | 上划线：$$ \overline{x^2+a+b} $$ 128 | 129 | 下划线：$$ \underline{Y_1-c-d} $$ 130 | 131 |
132 | 133 | ## 分数 134 | 135 | 分数使用 `\frac{partI}{partII}` 转义表达。 136 | 137 | ### 1. 实例代码 138 | 139 | ``` Markdown 140 | $$ \frac{2x+3}{3y-1} $$ 141 | ``` 142 | 143 | ### 2. 呈现效果 144 | 145 |
146 | 147 | $$ \frac{2x+3}{3y-1} $$ 148 | 149 |
150 | 151 | ## 方程组 152 | 153 | - 方式一：`\begin{array}{c} 表达式一\\表达式二... \end{array}` 154 | - 方式二：`\begin{cases}…\end{cases}` 155 | 156 | ### 1. 实例代码 157 | 158 | ``` Markdown 159 | $$ \begin{array}{c} 表达式一\\表达式二... \end{array} $$ 160 | ``` 161 | 162 | ### 2. 呈现效果 163 | 164 |
165 | 166 | $$ \begin{array}{c} a+b \\\\ c+d \end{array} $$ 167 | 168 |
169 | 170 | ## 大括号 171 | 172 | - 左大括号（`\left`）、右大括号（`\right`） 173 | - 格式：`\left(表达式\right)` 174 | 175 | ### 1. 实例代码 176 | 177 | ``` Markdown 178 | $$ \left(\frac{2x+3}{3y-1}\right) $$ 179 | ``` 180 | 181 | ### 2. 呈现效果 182 | 183 |
184 | 185 | $$ \left(\frac{2x+3}{3y-1}\right) $$ 186 | 187 |
188 | 189 | ## 开根号 190 | 191 | 格式：`\sqrt[n]{x}`，其中`n`表示开根次数，`x`表示被开方项。 192 | 193 | ### 1. 实例代码 194 | 195 | ``` Markdown 196 | $$ \sqrt[5]{6} $$ 197 | ``` 198 | 199 | ### 2. 呈现效果 200 | 201 |
202 | 203 | $$ \sqrt[5]{6} $$ 204 | 205 |
206 | 207 | ## 希腊字母 208 | 209 | - 大写：首字母大写`\Gamma`转义 210 | - 小写：首字母小写`\gamma`转义 211 | 212 | 希腊字母 | 表达式 | 希腊字母 | 表达式 213 | ------ | ------ | ------ | ------ 214 | $$ A $$ | A | $$ \alpha $$ | \alpha 215 | $$ B $$ | B | $$ \beta $$ | \beta 216 | $$ \Gamma $$ | \Gamma | $$ \gamma $$ | \gamma 217 | $$ \Delta $$ | \Delta | $$ \delta $$ | \delta 218 | $$ E $$ | E | $$ \epsilon $$ | \epsilon 219 | $$ Z $$ | Z | $$ \varepsilon $$ | \varepsilon 220 | $$ H $$ | H | $$ \eta $$ | \eta 221 | $$ \Theta $$ | \Theta | $$ \theta $$ | \theta 222 | $$ I $$ | I | $$ \iota $$ | \iota 223 | $$ K $$ | K | $$ \kappa $$ | \kappa 224 | $$ \Lambda $$ | \Lambda | $$ \lambda $$ | \lambda 225 | $$ M $$ | M | $$ \mu $$ | \mu 226 | $$ N $$ | N | $$ \nu $$ | \nu 227 | $$ \Xi $$ | \Xi | $$ \xi $$ | \xi 228 | $$ O $$ | O | $$ \omicron $$ | \omicron 229 | $$ \Pi $$ | \Pi | $$ \pi $$ | \pi 230 | $$ P $$ | P | $$ \rho $$ | \rho 231 | $$ \Sigma $$ | \Sigma | $$ \sigma $$ | \sigma 232 | $$ T $$ | T | $$ \tau $$ | \tau 233 | $$ \Upsilon $$ | \Upsilon | $$ \upsilon $$ | \upsilon 234 | $$ \Phi $$ | \Phi | $$ \phi $$ | \phi 235 | $$ - $$ | - | $$ \varphi $$ | \varphi 236 | $$ X $$ | X | $$ \chi $$ | \chi 237 | $$ \Psi $$ | \Psi | $$ \psi $$ | \psi 238 | $$ \Omega $$ | \Omega | $$ \omega $$ | \omega 239 | 240 | ## 运算符 241 | 242 | 运算符 | 表达式（转义） | 运算符 | 表达式（转义） 243 | ------ | ------ | ------ | ------ 244 | $$ \pm $$ | \pm | $$ \emptyset $$ | \emptyset 245 | $$ \times $$ | \times | $$ \in $$ | \in 246 | $$ \div $$ | \div | $$ \notin $$ | \notin 247 | $$ \mid $$ | \mid | $$ \subset $$ | \subset 248 | $$ \cdot $$ | \cdot | $$ \supset $$ | \supset 249 | $$ \circ $$ | \circ | $$ \subseteq $$ | \subseteq 250 | $$ \ast $$ | \ast | $$ \supseteq $$ | \supseteq 251 | $$ \bigodot $$ | \bigodot | $$ \bigcap $$ | \bigcap 252 | $$ \bigotimes $$ | \bigotimes | $$ \bigcup $$ | \bigcup 253 | $$ \bigoplus $$ | \bigoplus | $$ \bigvee $$ | \bigvee 254 | $$ \leq $$ | \leq | $$ \bigwedge $$ | \bigwedge 255 | $$ \geq $$ | \geq | $$ \neq $$ | \neq 256 | $$ \approx $$ | \approx | $$ \equiv $$ | \equiv 257 | 258 | ## 微积分符号 259 | 260 | 运算符 | 表达式（转义） | 运算符 | 表达式（转义） 261 | ------ | ------ | ------ | ------ 262 | $$ \oint $$ | \oint | $$ \infty $$ | \infty 263 | $$ \nabla $$ | \nabla | $$ - $$ | - 264 | 265 | ## 逻辑符号 266 | 267 | 运算符 | 表达式（转义） | 运算符 | 表达式（转义） 268 | ------ | ------ | ------ | ------ 269 | $$ \because $$ | \because | $$ \therefore $$ | \therefore 270 | $$ \forall $$ | \forall | $$ \exists $$ | \exists 271 | 272 | ## 特殊符号 273 | 274 | 含义 | 符号 | 表达式（转义） | 示例 275 | ------ | ------ | ------ | ------ 276 | 求和符号 | $$ \sum $$ | \sum | $$ \sum_{m=0}^\infty $$ 277 | 积分符号 | $$ \int $$ | \int | $$ \int_0^1 $$ 278 | 极限符号 | $$ \lim $$ | \lim | $$ \lim_{1 \to 6} \sum_{m=0}^\infty $$ 279 | 向量符号 | $$ \vec{} $$ | \vec{} | $$ \vec{M} $$ 280 | 281 | ## 使用`HTML`语法表达数学公式 282 | 283 | HTML5 支持在文档中使用 MathML 元素，在对应的标签是 `...` 中，使用`HTML`标签表达上标（``）、下标（``），以及上划线（``）等…… 284 | 285 | MathML 是数学标记语言，是一种基于XML（标准通用标记语言的子集）的标准，用来在互联网上书写数学符号和公式的置标语言。 286 | 287 | - MathML 呈现型元素（类别分类） 288 | - 顶层元素 289 | - `` 290 | - 字符/符号元素 291 | - `` 292 | - `` 293 | - `` 294 | - `` 295 | - `` 296 | - `` 297 | - `` 298 | - 通用布局元素 299 | - `` 300 | - `` 301 | - `` 302 | - `` 303 | - `` 304 | - `` 305 | - `` 306 | - `` 307 | - `` 308 | - `` 309 | - Script and limit elements 310 | - `` 311 | - `` 312 | - `` 313 | - `` 314 | - `` 315 | - `` 316 | - `` 317 | - `` 318 | - `` 319 | - Tabular math 320 | - `` 321 | - `` 322 | - `` 323 | - `` 324 | - `` 325 | - `` 326 | - Elementary math 327 | - `` 328 | - `` 329 | - `` 330 | - `` 331 | - `` 332 | - `` 333 | - `` 334 | - 尚无分类的元素 335 | - `` 336 | - 语义附注元素 337 | - `` 338 | - `` 339 | - `` 340 | - MathML 呈现型元素（字母排序） 341 | - math 342 | - ``（顶层元素） 343 | - A 344 | - ``（将动作绑定到子表达式） 345 | - ``（对齐分组） 346 | - ``（对齐点） 347 | - E 348 | - ``（包含的内容） 349 | - ``（包含的语法错误消息） 350 | - F 351 | - ``（圆括号） 352 | - ``（因子 Fraction） 353 | - G 354 | - ``（显示非标准符号） 355 | - I 356 | - ``（标识符） 357 | - L 358 | - ``（表格或矩阵中的行标签） 359 | - ``（长除法记号） 360 | - M 361 | - ``（惯例和张量指标） 362 | - N 363 | - ``（数量） 364 | - O 365 | - ``（运算符） 366 | - ``（上标） 367 | - P 368 | - ``（内容周围的填充空间） 369 | - ``（预留空间的不可见内容） 370 | - R 371 | - ``（带指定根数的根号） 372 | - ``（分组后的子表达式） 373 | - S 374 | - ``（字符串字面量） 375 | - ``（诸如进位的附注） 376 | - ``（单位进位， `` 的子元素） 377 | - ``（在 `` 和 `` 元素中分组后的若干行） 378 | - ``（在 `` 内部的水平行） 379 | - ``（空格） 380 | - ``（不带根数的平方根） 381 | - ``（在 `` 元素中的行） 382 | - ``（堆叠式对齐） 383 | - ``（样式变更） 384 | - ``（下角标） 385 | - ``（上角标） 386 | - ``（上下角标对） 387 | - T 388 | - ``（表格或矩阵） 389 | - ``（表格或矩阵中的单元格） 390 | - ``（文本） 391 | - ``（表格或矩阵中的行） 392 | - U 393 | - ``（下标） 394 | - ``（上标-下标对） 395 | - 其他元素 396 | - ``（语义附注的容器） 397 | - ``（数据附注） 398 | - ``（XML 附注） 399 | 400 | ### 1. 实例代码 401 | 402 | ``` Markdown 403 | 上标：x2 404 | 下标：x2 405 | 上划线：a + b + c 406 | 407 | 408 | 409 | a2 410 | + 411 | b2 412 | = 413 | c2 414 | 415 | 416 | 417 | 418 | 419 | A 420 | = 421 | 422 | 423 | 424 | x 425 | y 426 | 427 | 428 | z 429 | w 430 | 431 | 432 | 433 | 434 | 435 | ``` 436 | 437 | ### 2. 呈现效果 438 | 439 |
440 | 441 | 上标：x2 442 | 443 | 下标：y3 444 | 445 | 上划线：a + b + c 446 | 447 | 448 | 449 | a2 450 | + 451 | b2 452 | = 453 | c2 454 | 455 | 456 | 457 | 458 | 459 | A 460 | = 461 | 462 | 463 | 464 | x 465 | y 466 | 467 | 468 | z 469 | w 470 | 471 | 472 | 473 | 474 | 475 | 476 |
477 | -------------------------------------------------------------------------------- /src/html.md: -------------------------------------------------------------------------------- 1 | # Markdown 和 HTML 融合 2 | 3 | Markdown中，可以直接嵌入 `HTML` 内容，包括：`tags`，`css`等。 4 | 5 | - [嵌入HTML-tags](#嵌入html-tags) 6 | - [嵌入CSS](#嵌入css) 7 | 8 | ## 嵌入HTML-tags 9 | 10 | ### 1. 实例代码 11 | 12 | ``` HTML 13 |
14 | 15 | 1.做个耐心的聆听者。 16 | 17 | 2.永远不要流露出厌烦的表情。 18 | 19 | 3.等待，直到他人表明观点，然后附和他们。 20 | 21 | 4.让他人表明宗教立场，而后发表同样的观点。 22 | 23 | 5.可以暗示涉及“性”的话题，但若对方没有表示出强烈的兴趣，就不要继续下去。 24 | 25 | 6.永远不要谈论疾病，除非对方特别关心。 26 | 27 | 7.永远不要刺探个人隐私，对方最终会告诉你一切。 28 | 29 | 8.永远不要自吹自擂。 30 | 31 | 9.拒绝邋遢。 32 | 33 | 10.永远别喝醉。 34 | 35 |
36 | 37 |
38 | ``` 39 | 40 | ### 2. 呈现效果 41 | 42 |
43 | 44 | 1.做个耐心的聆听者。 45 | 46 | 2.永远不要流露出厌烦的表情。 47 | 48 | 3.等待，直到他人表明观点，然后附和他们。 49 | 50 | 4.让他人表明宗教立场，而后发表同样的观点。 51 | 52 | 5.可以暗示涉及“性”的话题，但若对方没有表示出强烈的兴趣，就不要继续下去。 53 | 54 | 6.永远不要谈论疾病，除非对方特别关心。 55 | 56 | 7.永远不要刺探个人隐私，对方最终会告诉你一切。 57 | 58 | 8.永远不要自吹自擂。 59 | 60 | 9.拒绝邋遢。 61 | 62 | 10.永远别喝醉。 63 |
64 | 65 |
66 | 67 | ## 嵌入CSS 68 | 69 | ### 1. 实例代码 70 | 71 | ``` HTML 72 |
73 | 74 | 80 | 81 |
82 | 生活赋予我们的一种巨大的和无限高贵的礼品，这就是青春：充满着力量，充满着期待、志愿，充满着求知和斗争的志向，充满着希望、信心的青春。 83 |
84 | 85 |
86 | 保尔·柯察金（Павел Корчагин, 英文：Pavel Korchagin）
87 | 88 |
89 | ``` 90 | 91 | ### 2. 呈现效果 92 | 93 |
94 | 95 | 101 | 102 |
103 | 生活赋予我们的一种巨大的和无限高贵的礼品，这就是青春：充满着力量，充满着期待、志愿，充满着求知和斗争的志向，充满着希望、信心的青春。 104 |
105 | 106 |
107 | 保尔·柯察金（Павел Корчагин, 英文：Pavel Korchagin）
108 | 109 |
110 | 111 |


112 | 113 | ------ 114 | -------------------------------------------------------------------------------- /src/imgs/blockquotes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bipou/markdown-guide/f091113d2f28ea1b9b729963037edb277865a6fb/src/imgs/blockquotes.png -------------------------------------------------------------------------------- /src/imgs/demo-image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bipou/markdown-guide/f091113d2f28ea1b9b729963037edb277865a6fb/src/imgs/demo-image.png -------------------------------------------------------------------------------- /src/imgs/emoji.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bipou/markdown-guide/f091113d2f28ea1b9b729963037edb277865a6fb/src/imgs/emoji.png -------------------------------------------------------------------------------- /src/imgs/tasklists.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bipou/markdown-guide/f091113d2f28ea1b9b729963037edb277865a6fb/src/imgs/tasklists.png -------------------------------------------------------------------------------- /src/intro.md: -------------------------------------------------------------------------------- 1 | # Markdown 介绍 2 | 3 | Markdown 是一种在 web 上设置文本样式的方法：使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。 4 | 5 | 你可以使用 Markdown 对文档的展示格式进行排版：如将文本格式化为粗体或斜体、添加图像，以及创建列表等。大多数情况下，Markdown只是一些普通文本加上一些非字母字符，比如 `#` 或者 `*`。 6 | 7 | Markdown 文档可以通过一些如 mdBook、gitBook 等应用转换为 HTML、PDF、DOC 等格式，提供给不同的应用场景。 8 | 9 | Markdown 的语法简洁明了、学习容易，而且功能比纯文本更强，因此使用非常广泛。如 GitHub、WordPress 等，使用 Markdown 对平台上的写作形式进行样式化，提供了 Markdown 文档直接展示的功能。 10 | 11 | ------ 12 | -------------------------------------------------------------------------------- /src/syntax-examples.md: -------------------------------------------------------------------------------- 1 | # Markdown 语法和实例 2 | 3 | 本章节语法和实例包括 Markdown 基础语法和实例，以及 GitHub 风格 Markdown（GitHub Flavored Markdown，简称 `GFM`）的语法扩展和特性实例。 4 | 5 | GitHub 风格 Markdown（GitHub Flavored Markdown，简称 `GFM`）是 GitHub 官方为了在 GitHub.com 上更容易地进行文本内容格式化展示，而提供的一组 Markdown 语法扩展及特性支持。 6 | 7 | > 💥 目前，GitHub 风格 Markdown（GitHub Flavored Markdown，简称 `GFM`）已经成为 Markdown 的通用标准，兼容于各种 Markdown 工具链和各类 Markdown 展示支持网站。 8 | 9 | GFM 对于 Markdown 的语法和特性有些为语法扩展，有些为新增特性。已经成为通用标准，各类 Markdown 工具链和展示网站兼容支持很完善，因此合并介绍。 10 | 11 | - [标题（Headers）](#标题headers) 12 | - [字体（Emphasis）](#字体emphasis) 13 | - [变量（Variables）](#变量variables) 14 | - [图像（Images）](#图像images) 15 | - [链接（Links）](#链接links) 16 | - [锚点（Anchors）](#锚点anchors) 17 | - [引用（Blockquotes）](#引用blockquotes) 18 | - [代码（Code）](#代码code) 19 | - [注释（Comment）](#注释comment) 20 | - [列表（Lists）](#列表lists) 21 | - [表格（Tables）](#表格tables) 22 | 23 | *主要应用于GitHub的Markdown扩展——* 24 | 25 | - [SHA引用](#SHA引用) 26 | - [Issue引用](#issue引用) 27 | - [用户通知（@mentions）](#用户通知mentions) 28 | - [表情符号（Emoji）](#表情符号emoji) 29 | 30 | ------ 31 | 32 | ## 标题（Headers） 33 | 34 | Markdown中共有6级标题，从 `#`、`##`、依次类推到 `######`。 35 | 36 | ### 1. 实例代码 37 | 38 | ``` Markdown 39 | # 一级标题 40 | ## 二级级标题 41 | ### 三级标题 42 | #### 四级级标题 43 | ##### 五级标题 44 | ###### 六级标题 45 | ``` 46 | 47 | ### 2. 呈现效果 48 | 49 |
50 | 51 | # 一级标题 52 | 53 | ## 二级级标题 54 | 55 | ### 三级标题 56 | 57 | #### 四级级标题 58 | 59 | ##### 五级标题 60 | 61 | ###### 六级标题 62 | 63 |
64 | 65 | ## 字体（Emphasis） 66 | 67 | - *斜体*：用 `*` 或者 `_` 包裹文本进行 _斜体_ 格式化。 68 | - **粗体**：用 `**` 或者 `__` 包裹文本进行 **粗体** 格式化。 69 | - 删除线：用`~~`包裹文本进行删除线格式化，部分工具和网站不支持展示。 70 | 71 | `**` 或者 `__`、`*` 或者 `_`，以及`~~` 可以 **_组合使用_**。 72 | 73 | ### 1. 实例代码 74 | 75 | ``` Markdown 76 | *这行文本是斜体* 77 | 78 | _这行文本是斜体_ 79 | 80 | **这行文本是粗体** 81 | 82 | __这行文本是粗体__ 83 | 84 | _这行文本是 **粗体** + 斜体_ 85 | 86 | ~~_这行文本是 **粗体** + 斜体_ + 删除线~~ 87 | ``` 88 | 89 | ### 2. 呈现效果 90 | 91 |
92 | 93 | *这行文本是斜体* 94 | 95 | _这行文本是斜体_ 96 | 97 | **这行文本是粗体** 98 | 99 | __这行文本是粗体__ 100 | 101 | _这行文本是 **粗体** + 斜体_ 102 | 103 | _这行文本是 **粗体** + 斜体_ + 删除线 104 | 105 |
106 | 107 | ## 变量（Variables） 108 | 109 | Markdown 中支持**变量定义**和**变量引用**，且支持**中文**。 110 | 111 | - 变量定义：`[key]: value` 112 | - 变量引用：`[key]`、`[text][key]` 113 | 114 | ### 1. 实例代码 115 | 116 | ``` Markdown 117 | 定义链接：[Markdown指南]: https://markdown-guide.rusthub.org 118 | 119 | 引用链接： 120 | 121 | key引用：[Markdown指南] 122 | 123 | value引用：[未定义文本][Markdown指南] 124 | ``` 125 | 126 | ### 2. 呈现效果 127 | 128 |
129 | 130 | [Markdown指南]: https://markdown-guide.rusthub.org 131 | 132 | 引用链接： 133 | 134 | key引用：[Markdown指南] 135 | 136 | value引用：[未定义文本][Markdown指南] 137 | 138 |
139 | 140 | ## 图像（Images） 141 | 142 | 格式：`![Alt Text](url)` 143 | 144 | ### 1. 实例代码 145 | 146 | ``` Markdown 147 | ![Demo Image](./imgs/demo-image.png) 148 | ``` 149 | 150 | ### 2. 呈现效果 151 | 152 |
153 | 154 | ![Demo Image](./imgs/demo-image.png) 155 | 156 |
157 | 158 | ## 链接（Links） 159 | 160 | Markdown中可对url链接自动识别，但有些Markdown工具不支持（GitHub支持自动识别）。 161 | 162 | 若需指定url链接文本，格式：`[文本](url)`。 163 | 164 | ### 1. 实例代码 165 | 166 | ``` Markdown 167 | [Markdown指南](https://markdown-guide.rusthub.org) 168 | 169 | https://markdown-guide.rusthub.org 170 | 171 | markdown-guide.rusthub.org 172 | ``` 173 | 174 | ### 2. 呈现效果 175 | 176 |
177 | 178 | [Markdown指南](https://markdown-guide.rusthub.org) 179 | 180 | [https://markdown-guide.rusthub.org](https://markdown-guide.rusthub.org) 181 | 182 | [markdown-guide.rusthub.org](https://markdown-guide.rusthub.org) 183 | 184 |
185 | 186 | ## 锚点（Anchors） 187 | 188 | 格式：`[锚点文本](#锚点链接)`。需要注意如下几点： 189 | 190 | - 欲定位的锚点链接必须是标题，即`#`、`###`等定义的6级标题； 191 | - 不管标题大小写，锚点均为小写； 192 | - 可以使用中文做锚点，中文锚点需要省略`（`、`、`等中文标点符号。 193 | 194 | ### 1. 实例代码 195 | 196 | ``` Markdown 197 | 标题：## 锚点（Anchors） 198 | 锚点：[锚点（Anchors）](#锚点anchors) 199 | ``` 200 | 201 | ### 2. 呈现效果 202 | 203 |
204 | 205 | [锚点（Anchors）](#锚点anchors) 206 | 207 |
208 | 209 | ## 引用（Blockquotes） 210 | 211 | Markdown中通过`>`实现引用。引用可以多级嵌套：`>>`,`>>>`；也可以和其它Markdown语法嵌套，比如无序列表。 212 | 213 | ### 1. 实例代码 214 | 215 | ``` Markdown 216 | > 一级文本引用 217 | >> 二级文本引用 218 | 219 | 引用中嵌套无序列表 220 | 221 | >> * 这是第一项 222 | >> * 这是第二项 223 | ``` 224 | 225 | ### 2. 呈现效果 226 | 227 |
228 | 229 | 不同工具和输出呈现效果有差别，如下两种—— 230 | 231 | **Markdown预览呈现** 232 | 233 | ![blockquotes](./imgs/blockquotes.png) 234 | 235 | **输出HTML呈现** 236 | 237 | > 一级文本引用 238 | >> 二级文本引用 239 | 240 | 引用中嵌套无序列表 241 | 242 | >> - 这是第一项 243 | >> - 这是第二项 244 | 245 |
246 | 247 | ## 代码（Code） 248 | 249 | Markdown中代码格式化可以通过三种方式： 250 | 251 | - 行内式：通过一对 ` 包裹单行代码实现； 252 | - 代码块：通过一对 ``` 包裹实现，可以指定代码的编程语言，如`Python`、`JavaScript`、`Rust`等，且支持**语法高亮**； 253 | - 缩进式：通过缩进 `>=` 4空格实现，部分支持语法高亮。 254 | 255 | ### 1. 实例代码 256 | 257 | ``` Markdown 258 | 行内式代码：`import os, sys` 259 | 260 | 代码块（无需缩进）： 261 | ``` Python 262 | import os, sys 263 | 264 | sys.path 265 | 266 | print(os) 267 | ``` 268 | 269 | 缩进式： 270 | if (isAwesome){ 271 | return true 272 | } 273 | ``` 274 | 275 | ### 2. 呈现效果 276 | 277 |
278 | 279 | 行内式代码：`import os, sys` 280 | 281 | 代码块（无需缩进）： 282 | 283 | ``` Python 284 | import os, sys 285 | 286 | sys.path 287 | 288 | print(os) 289 | ``` 290 | 291 | 缩进式： 292 | 293 | if (isAwesome){ 294 | return true 295 | } 296 | 297 |
298 | 299 | ## 注释（Comment） 300 | 301 | Markdown中注释可以通过二种方式实现： 302 | 303 | - HTML注释：用``标签来实现注释； 304 | - HTML标签：用HTML标签显示属性`style='display: none'`标签来实现注释； 305 | - HACK方法：用`Markdown解析原理`来实现注释。 306 | 307 | _注：HACK方法基于`Markdown解析原理`，相较于`HTML注释`和`HTML标签显示属性`要稳定得多，但语义化差。_ 308 | 309 | > HACK方法注释写法很灵活，基于Markdown解析原理即可。以下实例代码仅试举几例，读者可自由组合。 310 | 311 | ### 1. 实例代码 312 | 313 | ``` Markdown 314 | HTML注释 ： 315 | 316 | 317 | 318 | 323 | 324 | HTML标签实现注释： 325 | 326 |
327 | 我是注释， 328 | 多行段落， 329 | 不会在浏览器中显示。 330 |
331 | 332 | HACK方法注释（此处仅是举例，读者可以利用Markdown解析原理自由组合语法）： 333 | 334 | [](我是注释，不会在浏览器中显示。) 335 | 336 | [注释关键字]:(注释描述。) 337 | 338 | [#]:<> (我是注释，不会在浏览器中显示。) 339 | [#]:# (我是注释，不会在浏览器中显示。) 340 | [注释]:<> (我是注释，不会在浏览器中显示。) 341 | [注释]:# (我是注释，不会在浏览器中显示。) 342 | [注释]:// (我是注释，不会在浏览器中显示。) 343 | [//]:<> (我是注释，不会在浏览器中显示。) 344 | [//]:# (我是注释，不会在浏览器中显示。) 345 | ``` 346 | 347 | ### 2. 呈现效果 348 | 349 |
350 | 351 | HTML注释 ： 352 | 353 | 354 | 355 | 360 | 361 | HTML标签实现注释： 362 | 363 |
364 | 我是注释， 365 | 多行段落， 366 | 不会在浏览器中显示。 367 |
368 | 369 | HACK方法注释（此处仅是举例，读者可以利用Markdown解析原理自由组合语法）： 370 | 371 | [](我是注释，不会在浏览器中显示。) 372 | 373 | [注释关键字]:(注释描述。) 374 | 375 | [#]:<> (我是注释，不会在浏览器中显示。) 376 | [#]:# (我是注释，不会在浏览器中显示。) 377 | [注释]:<> (我是注释，不会在浏览器中显示。) 378 | [注释]:# (我是注释，不会在浏览器中显示。) 379 | [注释]:// (我是注释，不会在浏览器中显示。) 380 | [//]:<> (我是注释，不会在浏览器中显示。) 381 | [//]:# (我是注释，不会在浏览器中显示。) 382 | 383 |
384 | 385 | ## 列表（Lists） 386 | 387 | 列表分为`无序列表`、`有序列表`，以及`任务列表`。 388 | 389 | ### 无序列表 390 | 391 | 无序列表用`-`定义，**下级列表相对于上级 `缩进空格 >= 2`** 392 | 393 | #### 1. 实例代码 394 | 395 | ``` Markdown 396 | - 第一节 397 | - 第二节 398 | - 第一条（缩进空格2个） 399 | - 第二条 400 | ``` 401 | 402 | #### 2. 呈现效果 403 | 404 |
405 | 406 | - 第一节 407 | - 第二节 408 | - 第一条（缩进空格2个） 409 | - 第二条 410 | 411 |
412 | 413 | ### 有序列表 414 | 415 | 有序列表`数字.`定义，**下级列表相对于上级 `缩进空格 > 2`** 416 | 417 | #### 1. 实例代码 418 | 419 | ``` Markdown 420 | 1. 第一节 421 | 1. 第二节 422 | 1. 第三节 423 | 1. 第一条（缩进空格3个） 424 | 1. 第二条 425 | ``` 426 | 427 | #### 2. 呈现效果 428 | 429 |
430 | 431 | 1. 第一节 432 | 1. 第二节 433 | 1. 第三节 434 | 1. 第一条（缩进空格3个） 435 | 1. 第二条 436 | 437 |
438 | 439 | ### 任务列表 440 | 441 | `任务列表`是一个任务进度指示器，也可使用与拉取请求。 442 | 443 | *注*：`任务列表`仅在部分Markdown工具软件或者网站支持展示，如GitHub；不是全部，使用前需要验证是否被支持。 444 | 445 | #### 1. 实例代码 446 | 447 | ``` Markdown 448 | - [x] 表情符号、引用API，以及标签已被支持。 449 | - [x] 语法分析已经完成。 450 | - [x] 此项已完成。 451 | - [ ] 此项未完成。 452 | ``` 453 | 454 | #### 2. 呈现效果 455 | 456 |
457 | 458 | ![task lists](./imgs/tasklists.png) 459 | 460 |
461 | 462 | ## 表格（Tables） 463 | 464 | - 通过字符组合单元格，用管道分隔符 `|` 来分割单元格；无需上下对齐。 465 | - 通过连字符 `-` 来声明表头，仅第一行底部需要。 466 | - 通常情况下，表格默认**居中**。 467 | 468 | ### 1. 实例代码 469 | 470 | ``` Markdown 471 | 表头一 | 表头二 | 表头三 472 | ------- | ------ | ------ 473 | 一行单元格一 | 一行单元格二 | 一行单元格三 474 | 二行内容一 | 二行内容二 | 二行内容三 475 | 三行描述部分一 | 三行描述部分二 | 三行描述部分三 476 | ``` 477 | 478 | ### 2. 呈现效果 479 | 480 |
481 |
482 | 483 | 表头一 | 表头二 | 表头三 484 | ------ | ------ | ------ 485 | 一行单元格一 | 一行单元格二 | 一行单元格三 486 | 二行内容一 | 二行内容二 | 二行内容三 487 | 三行描述部分一 | 三行描述部分二 | 三行描述部分三 488 | 489 |
490 |
491 | 492 | ## 主要应用于GitHub的Markdown扩展 493 | 494 | ### SHA引用 495 | 496 | GitHub仓库中，任何对提交（git commit）的SHA-1散列（哈希值）的引用都将自动转换为指向GitHub上提交的链接。 497 | 498 | ``` Markdown 499 | 16c999e8c71134401a78d4d46435517b2271d6ac 500 | mojombo@16c999e8c71134401a78d4d46435517b2271d6ac 501 | mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac 502 | ``` 503 | 504 | ### Issue引用 505 | 506 | 在GitHub仓库中，任何涉及`Issue`或`拉请求`的数字都将自动转换为链接。 507 | 508 | ``` Markdown 509 | #1 510 | mojombo#1 511 | mojombo/github-flavored-markdown#1 512 | ``` 513 | 514 | ### 用户通知（@mentions） 515 | 516 | 在GitHub仓库的Issues中，`@`符号后输入用户名，就会通知此用户来查看评论。GitHub中称此为`@mention`。 517 | 518 | 不仅可以通知用户，还可以`@`通知*所在组织*中的团队。 519 | 520 | ### 表情符号（Emoji） 521 | 522 | GitHub支持[表情符号](https://help.github.com/en/articles/basic-writing-and-formatting-syntax#using-emoji)，格式为：`:EMOJICODE:`。 523 | 524 | ``` Markdown 525 | @zzy :+1: 这个PR看起来非常好 - 可以合并到主仓库了！ :shipit: 526 | ``` 527 | 528 | 在GitHub中，会渲染为如下效果—— 529 | 530 | ![emoji](./imgs/emoji.png) 531 | 532 | GitHub支持的表情符号很多，详细请查看[表情符号清单](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md)。 533 | 534 |


535 | 536 | ------ 537 | -------------------------------------------------------------------------------- /src/toolchain.md: -------------------------------------------------------------------------------- 1 | # Markdown 工具链 2 | 3 | 目前，使用 Markdown 进行书籍或者文章编写的工具很多，且大多开源，基础功能免费。概括来说，分为命令行工具和编辑器两种，下面介绍一些受众较多的工具链。 4 | 5 | ## 命令行工具 6 | 7 | ### mdBook 8 | 9 | 本指南即采用`mdBook`编写，在此强烈推荐。 10 | 11 | > 💥 mdBook的使用教程，可访问**同步最新开发版**的[中文用户指南-https://mdbook-guide.rusthub.org](https://mdbook-guide.rusthub.org)。 12 | 13 | `mdBook`是一个命令行工具，可以使用`Markdown`文件创建书籍。采用[Rust](http://www.rust-lang.org)语言编写，运行速度非常快。 14 | 15 | 可以输出`HTML`、`PDF`、`eBook`等格式的电子书，功能强大，使用方便。 16 | 17 | `mdBook`提供更低层次API的封装，除了编写书籍、文档外，还可以由Rustdoc生成API文档。 18 | 19 | `mdBook`是免费的开源软件，可以在[GitHub上找到源代码](https://github.com/rust-lang-nursery/mdBook)。开发团队非常活跃，响应和维护都很积极，使用问题和Bug可以发布在[GitHub Issue跟踪器](https://github.com/rust-lang-nursery/mdBook/issues)。 20 | 21 | ### gitBook 22 | 23 | gitBook是一个基于Node.js的命令行工具，开发周期长，比较成熟。支持Markdown和AsciiDoc两种语法格式，可以输出HTML、PDF、eBook等格式的电子书。 24 | 25 | gitBook是开源软件，可以在[GitHub上找到源代码](https://github.com/GitbookIO/gitbook)。 26 | 27 | ## 编辑器 28 | 29 | Markdown编辑器众多，简单易用。 30 | 31 | 1. 通过安装插件支持Markdown开发：vsCode、vim、sublime text、JetBrains IDE和Eclipse IDE等。 32 | 33 | 下表是笔者推荐的、较受欢迎的、通过插件支持Markdown开发的编辑器，仅供参考。 34 | 35 | 名称 | 插件 | 运行平台 | 是否免费 36 | ------ | ------ | ------ | ------ 37 | Visual Studio Code | 插件很多，如：
Markdownlint、
Markdown All in One、
Markdown PDF | macOS、Windows、Linux | 免费 38 | Vim | 插件很多，如：
vim-markdown、
markdown-preview、
vim-instant-markdown | macOS、Windows、Linux | 免费 39 | Sublime Text | 插件很多，如：
MarkdownEditing、
OmniMarkupPreviewer | macOS、Windows、Linux | 免费+收费 40 | JetBrains IDE、
Eclipse IDE | 可从IDE市场搜索插件，
官方和开发者均有提供 | macOS、Windows、Linux | 免费+收费 41 | 42 | 2. 专用于支持Markdown开发：typora、macDown、bear、markdownPad、markdownX、Atom、简书、CSDN以及GitBook自家的GitBook Editor等等。 43 | 44 | 下表是部分较受欢迎的、专用于支持Markdown开发的编辑器，仅供参考。 45 | 46 | 名称 | 说明 | 运行平台 | 是否免费 47 | ------ | ------ | ------ | ------ 48 | gitBook Editor | 和gitBook无缝集成的编辑器 | macOS、Windows、Linux | 免费 + 收费 49 | markdownPad | Windows上强大的编辑器 | Windows | 免费 + 收费 50 | bear | 功能齐全的编辑器 | iPhone、iPad、macOS | 免费 + 内购 51 | typora | 所见即所得的编辑器 | macOS、Windows、Linux | 免费 52 | macDown | macOS上强大的编辑器 | macOS | 免费 53 | markdownX | Android上的轻量编辑器 | Android | 免费 54 | 55 |


56 | 57 | ------ 58 | --------------------------------------------------------------------------------