论坛 › 经验交流 › Markdown学习手册

Guangran 发表于 2025-4-8 20:16:16

Markdown学习手册

本帖最后由 Guangran 于 2025-4-8 20:18 编辑

<h2>前言</h2>
<p>EmulatedLab 论坛支持 Markdown 写作了，这里写一篇简单的教程介绍一下 Markdown 以供大家参考。</p>
<h2># Markdown概述</h2>
<p>Markdown是一种轻量级标记语言，它允许人们使用易读、易写的纯文本格式编写文档。</p>
<h3>起源</h3>
<p>据GitHub Flavored Markdown（GFM）官方文档介绍， Markdown是由约翰·格鲁伯（John Gruber）在亚伦·斯沃茨（Aaron Swartz）的帮助下开发，并在2004年发布的标记语言。</p>
<p>其设计灵感主要来源于纯文本电子邮件的格式，目标是让人们能够使用易读、易写的纯文本格式编写文档，而且这些文档可以转换为HTML（Hyper Text Markup Language，超文本标记语言）文档。</p>
<p>简单点说，Markdown就是由一些简单的符号（如 <code>* / - &gt; [] () #</code>）组成的用于排版的标记语言，其最重要的特点就是可读性强。</p>
<p>Markdown相当于简化了的HTML，它只提供用户最常用的语法格式，更易读和易写，用户可以不必关心复杂的HTML标签，只专注于写作就行了。</p>
<h3>演进</h3>
<p>起初Markdown主要用于网络写作，后来人们希望Markdown能够应用到更多的领域，如写书、记笔记、写文档、写幻灯片等。由于Markdown本身功能有限，一些特定的需求和场景无法被满足，因此产生<br />
了许多扩展语法，这些语法在基础语法之上新增了如表格、任务列表、围栏代码块等功能。</p>
<h2># 基础语法</h2>
<h3>字体</h3>
<h4>1. 标题</h4>
<p>在Markdown语法中，标题支持使用两种标记：底线（<code>-/=</code>）和 <code>#</code>。</p>
<h5>使用底线的语法如下：</h5>
<pre><code>这是一个标题
===
</code></pre>
<pre><code>这是一个标题
---
</code></pre>
<p><strong>语法说明：</strong></p>
<p>1）底线是 <code>=</code>表示一级标题。</p>
<p>2）底线是 <code>-</code>表示二级标题。</p>
<p>3）底线符号的数量至少2个。</p>
<p>4）这种语法只支持这两级标题。</p>
<h5>使用#的语法如下：</h5>
<pre><code class="language-markdown"># 这是一个一级标题
## 这是一个二级标题
### 这是一个三级标题
</code></pre>
<p><strong>语法说明：</strong></p>
<p>1）在行首插入 <code>#</code>可标记出标题。</p>
<p>2）<code>#</code>的个数表示了标题的等级。</p>
<p>3）建议在 <code>#</code>后加一个空格。</p>
<p>4） Markdown中最多只支持前六级标题</p>
<h5>语法规范</h5>
<ol>
<li>建议使用 <code>#</code>标记标题，而不是 <code>===</code>或 <code>---</code>，因为后者会难以阅读和维护。</li>
<li>要保持间距，建议标题的前后都要空1行（除非标题在文档开头）；<code>#</code>与标题文本之间也要有1个空格，否则会导致阅读困难。</li>
<li>不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格。</li>
<li>建议标题的结尾不要有标点符号，如句号、逗号、冒号、分号等。</li>
<li>建议标题要尽量简短，这样方便引用，特别是当生成目录时。如果原拟的标题是一个长句，可以从长句中提取标题，而将长句作为标题下的内容。</li>
</ol>
<h4>2. 粗体和斜体</h4>
<p>在Markdown中，粗体由两个 <code>*</code>或两个 <code>_</code>包裹，斜体由1个 <code>*</code>或1个 <code>_</code>包裹。</p>
<h5>粗体格式的语法如下：</h5>
<pre><code class="language-markdown">**粗体**
或
__粗体__
</code></pre>
<h5>斜体格式的语法如下：</h5>
<pre><code class="language-markdown">*斜体*
或
_斜体_
</code></pre>
<h5>语法规范</h5>
<ol>
<li>建议粗体使用2个 <code>*</code>包裹，斜体使用1个 <code>*</code>包裹，因为 <code>*</code>比较常见，而且比 <code>_</code>可读性更强。</li>
<li>在粗体和斜体语法标记的内部，建议不要有空格。</li>
</ol>
<h3>段落与换行</h3>
<p>Markdown中的段落由一行或多行文本组成，不同的段落之间使用空行来标记。</p>
<p><strong>语法说明：</strong></p>
<p>1）如果行与行之间没有空行，则会被视为同一段落。</p>
<p>2）如果行与行之间有空行，则会被视为不同的段落。</p>
<p>3）空行是指行内什么都没有，或者只有空格和制表符。</p>
<p>4）如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。</p>
<p><strong>语法规范：</strong></p>
<p>为了便于阅读，应该限制每行字符的数量，通常每行不超过80个字符，可以在编辑器中进行设置。</p>
<p><strong>关于换行，建议如下：</strong></p>
<p>1）当超过80个字符后进行换行。</p>
<p>2）在一句话结束（<code>。</code>或 <code>！</code>或 <code>？</code>）之后换行。</p>
<p>3）当URL较长时换行。</p>
<p>通常URL较长会导致行字符数量超过限制，为了提高可读性，可以在URL之前加一个换行符。</p>
<h4>1. 列表</h4>
<p>在Markdown中支持使用有序列表和无序列表，有序列表用 <code>数字序号</code>+<code>英文句号</code>+<code>空格</code>+<code>列表内容</code>来标记，无序列表由 <code>*</code>/<code>+</code>/<code>-</code> +<code>空格</code>+<code>列表内容</code>来标记。</p>
<h5>有序列表的语法如下:</h5>
<pre><code class="language-markdown">数字序号 + 英文句号 + 空格 + 列表内容
</code></pre>
<h5>无序列表的语法如下:</h5>
<pre><code class="language-markdown">*/+/- + 空格 + 列表内容
</code></pre>
<h5>嵌套列表的语法示例如下:</h5>
<pre><code class="language-markdown">+ 第一层列表
TAB + 第二层列表
TAB + TAB + 第三层列表
</code></pre>
<p><strong>语法说明如下：</strong></p>
<p>1）列表中可以嵌套列表。</p>
<p>2）有序列表和无序列表也可以互相嵌套。</p>
<h5>使用规范</h5>
<p>1） 建议使用 <code>-</code>来标记无序列表，因为 <code>*</code>容易跟粗体和斜体混淆，而 <code>+</code>不流行。</p>
<p>2） 如果一个列表中所有的列表项都没有换行，建议使用1个空格。</p>
<p>3） 如果列表项有换行，则建议给无序列表使用3个空格，给有序列表使用2个空格。</p>
<p>4） 如果一个列表中的每个列表项都只有1行，建议列表项之间不要有空行。</p>
<p>5） 如果列表项中有换行，建议在列表项之间空1行，这样会比较容易区分多行列表项的开始和结束。</p>
<p>6） 建议在列表前/后都空1行。</p>
<p>7） 数字、字符、符号列表使用英文半角句号，句号后加空格。</p>
<h4>2. 分隔线</h4>
<p>在Markdown中，分隔线由 <code>3</code>个以上的 <code>*</code>/<code>-</code>/<code>_</code>来标记。</p>
<h5>使用分割线的语法如下</h5>
<pre><code>***
或
---
或
___
</code></pre>
<h5>语法说明</h5>
<p>1）分隔线须使用至少3个以上的 <code>*</code>/<code>-</code>/<code>_</code>来标记。</p>
<p>2）行内不能有其他的字符。</p>
<p>3）可以在标记符中间加上空格。</p>
<h3>图片</h3>
<h5>插入图片的语法如下</h5>
<pre><code class="language-markdown">
</code></pre>
<p><strong>语法说明如下：</strong></p>
<p>1）图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。</p>
<p>2）图片地址可以是本地图片的路径也可以是网络图片的地址。</p>
<p>3）本地图片支持相对路径和绝对路径两种方式。</p>
<h3>链接</h3>
<h4>1. 文字链接</h4>
<p>文字链接就是把链接地址直接写在文本中。语法是用方括号包裹链接文字，后面紧跟着括号包裹的链接地址，语法如下所示：</p>
<pre><code class="language-bash">[链接文字](链接地址)
</code></pre>
<h4>2. 引用链接</h4>
<p>引用链接是把链接地址作为“变量”先在 Markdown 文件的页尾定义好，然后在正文中进行引用。其语法如下：</p>
<pre><code class="language-markdown">在正文中引用链接标记，可以理解为引用定义好的变量：
[链接文字][链接标记]
在底部定义链接标记，可以理解为定义一个地址变量：
[链接标记]: 链接地址
</code></pre>
<p><strong>语法说明如下：</strong></p>
<p>1）链接标记可以有字母、数字、空格和标点符号。</p>
<p>2）链接标记不区分大小写。</p>
<p>3）定义的链接内容可以放在当前文件的任意位置，建议放在页尾。</p>
<p>4）当链接地址为网络地址时要以http/https开头，否则会被识别为本地地址。</p>
<h4>3. 网址链接</h4>
<p>在 Markdown 中，将网络地址或邮箱地址使用 <code>&lt;&gt;</code>包裹起来会被自动转换为超链接。其语法如下：</p>
<pre><code class="language-markdown">&lt;URL 或邮箱地址&gt;
</code></pre>
<h4>4. 使用规范</h4>
<ol>
<li>在Markdown中，链接标题的信息应该更丰富，从标题中应该可以知道链接的内容，要使用有意义的链接标题。</li>
<li>建议使用 <code>&lt;&gt;</code>包裹自动链接，这种方式更通用。</li>
<li>自动链接要以 http/https 开头。</li>
</ol>
<h3>行内代码与代码块</h3>
<h4>1. 行内代码</h4>
<p>在Markdown中，行内代码引用使用`包裹，语法如下：</p>
<pre><code class="language-markdown">`代码`
</code></pre>
<h4>2. 代码块</h4>
<p>在Markdown中，代码块以Tab键或4个空格开头，语法如下。</p>
<pre><code>以 Tab 键开头：
        def test_print():
                pass
或者以 4 个空格开头：
    def test_print():
      pass
</code></pre>
<blockquote>
<p>[!point]因为代码块使用 Tab 键或 4 个空格开头的效果不够直观，很多扩展语法（如 GFM）提供了围栏代码块，并且支持语法高亮。</p>
</blockquote>
<h4>3. 使用规范</h4>
<ol>
<li>除行内代码可以使用`包裹以外，如果我们想转义或强调某些字符，也可以使用`包裹。</li>
<li>如果代码超过1行，请使用围栏代码块（扩展语法），并显式地声明语言，这样做便于阅读，并且可以显示语法高亮。但如果我们编写的是简单的代码片段，使用 4 个空格缩进的代码块也许更清晰。</li>
<li>很多Shell命令都要粘贴到终端中去执行，因此最好避免在Shell命令中使用任何换行操作；可以在行尾使用一个 <code>\</code>，这样既能避免命令换行，又能提高源码的可读性。</li>
<li>建议不要在没有输出内容的Shell命令前加 <code>$</code>。在命令没有输出内容的情况下，<code>$</code>是没有必要的，因为内容全是命令，我们不会把命令和输出的内容混淆。</li>
<li>建议在有输出内容的Shell命令前加上 <code>$</code>，这样会比较容易区分命令和输出的内容。</li>
</ol>
<h3>引用</h3>
<h5>语法</h5>
<p>在Markdown中，引用由 <code>&gt;</code>+<code>引用内容</code>来标记，如下所示：</p>
<pre><code class="language-markdown">&gt; 引用内容
</code></pre>
<p><strong>语法说明如下。</strong></p>
<p>1）多行引用也可以在每一行的开头都插入 <code>&gt;</code>。</p>
<p>2）在引用中可以嵌套引用。</p>
<p>3）在引用中可以使用其他的Markdown语法。</p>
<p>4）段落与换行的格式在引用中也是适用的。</p>
<h5>使用规范</h5>
<ol>
<li>建议在引用的标记符号 <code>&gt;</code>之后添加一个空格。</li>
<li>建议每一行引用都使用符号 <code>&gt;</code>。</li>
<li>不要在引用中添加空行。</li>
</ol>
<h3>转义</h3>
<p>当我们想在Markdown文件中插入一些标记符号，但又不想让这些符号被渲染时，可以使用 <code>\</code>进行转义，语法如下：</p>
<pre><code class="language-markdown">\特殊符号
</code></pre>
<p><strong>可被转义的符号：</strong></p>
<pre><code>\ 反斜线
` 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
+ 加号
- 减号
. 英文句点
! 感叹号
</code></pre>
<h2># 扩展语法GFM</h2>
<h3>围栏代码块</h3>
<p>在基础语法中，代码块使用Tab键或4个空格开头；在扩展语法中，围栏代码块使用连续3个`或3个~包裹，还支持语法高亮，可读性和可维护性更强一些。</p>
<h5>围栏代码块语法如下：</h5>
<pre><code>```python
代码片段
```
或
~~~python
代码片段
~~~
</code></pre>
<h5>语法说明如下：</h5>
<p>围栏代码块使用连续3个`或3个~包裹，支持语法高亮并可以加上编程语言的名字。</p>
<h2># Markdown编辑软件——Typora</h2>
<p>Typora是一款功能全面、简洁高效，而且又非常优雅的 Markdown 编辑器。它把源码编辑和效果预览合二为一，在输入标记之后随即生成预览效果，提供了“所见即所得”的Markdown写作体验。</p>
<h4>主要特性：</h4>
<p>1）实时预览：传统的Markdown编辑器都有两个窗口，左边是源码，右边是渲染后的效果。 Typora独辟蹊径，把源码编辑和效果预览合二为一，实现了真正的所见即所得。</p>
<p>2）扩展语法：Typora不光支持GFM，还扩展了数学公式、流程图等功能。</p>
<p>3）快捷操作：Typora对几乎所有的Markdown标记都提供了快捷操作方式，使用起来非常高效。</p>
<p>4）界面漂亮：默认支持6种主题，可自定义，好看又好用。</p>
<p>5）文件转换：支持多种文件格式通过导入/导出功能跟.md格式相互转换。</p>
<p>6）支持中文：支持中文，可以帮助大家更好地理解各项功能。</p>
<p>7）视图模式：支持大纲和文档列表视图，方便在不同段落和不同文件之间进<br />
行切换。</p>
<p>8）跨平台：支持macOS、 Windows和Linux系统。</p>
<h4>下载安装：</h4>
<p>下载地址：<a href="https://typoraio.cn/">Typora 官方中文站 (typoraio.cn)</a></p>
<h2># 最后</h2>
<p>更多信息可以参考以下网址</p>
<p>Markdown官网：<a href="https://daringfireball.net/projects/markdown/">https://daringfireball.net/projects/markdown/</a></p>
<p>GFM官方文档：<a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a></p>
<blockquote>
<p>【参考文档】<br />
了不起的 Markdown / 毕小朋著. —北京：电子工业出版社， 2019.8</p>
</blockquote>

ary8888 发表于 2025-4-16 21:01:45

感谢楼主，值得学习Markdown这个东西的。

查看完整版本: Markdown学习手册