Markdown 注釋

1. 前言

在任何一款現(xiàn)代程序語(yǔ)言中，注釋都是至關(guān)重要的，它是源代碼文件提升可讀性的重要補(bǔ)充，也是多人協(xié)作時(shí)的重要工具。

Markdown 的注釋可以通過三種方法實(shí)現(xiàn)：第一是通過 html 的 <!-- --> 標(biāo)記；第二可以通過樣式隱藏段落內(nèi)容，即 <div style="display:none">；第三是通過 Markdown 自身的解析原理實(shí)現(xiàn)。

環(huán)境說明：
考慮到 Markdown 工具之間的不兼容，有的內(nèi)容直接從頁(yè)面復(fù)制粘貼到本地不會(huì)正常顯示，大家學(xué)習(xí)時(shí)自己動(dòng)手寫是肯定沒問題的。本節(jié)所有實(shí)例代碼及演示效果均使用 Typora 工具完成。
本節(jié)所有截圖均為 Typora 導(dǎo)出 HTML 后網(wǎng)頁(yè)的渲染效果。

2. 語(yǔ)法詳解

2.1 使用原生 HTML 注釋語(yǔ)法

因?yàn)?Markdown 文檔是基于 HTML 實(shí)現(xiàn)的，所以可以通過 HTML 原生對(duì)注釋的支持實(shí)現(xiàn)文檔注釋效果。

實(shí)例 1：

#### 基于 HTML 標(biāo)簽的注釋

<!-- 這是一段被注釋掉的文字 -->

這是一段沒有被注釋的文字

其渲染結(jié)果如下：

其轉(zhuǎn)換后的 html 的內(nèi)容如下：

<p>這是一段沒有被注釋的文字</p>

請(qǐng)注意：此種方法被注釋的內(nèi)容是不被渲染輸出的。

2.2 使用 HTML 樣式實(shí)現(xiàn)隱藏

這種方式原則上并不是注釋，而是將內(nèi)容隱藏，已達(dá)到注釋效果。

實(shí)例 2：

#### 基于 HTML 樣式

<div style="display:none">
這是一段被注釋掉的文字
</div>

這是一段沒有被注釋的文字

其渲染結(jié)果如下：

其轉(zhuǎn)換后的 html 的內(nèi)容如下：

<h4 id="基于-html-樣式">基于 HTML 樣式</h4>
<div style="display:none">
這是一段被注釋掉的文字
</div>

<p>這是一段沒有被注釋的文字</p>

請(qǐng)注意：此種方法被注釋的內(nèi)容是會(huì)被渲染輸出的，只是在輸出時(shí)會(huì)被隱藏。

2.3 通過 Markdown 自身的解析功能

這種方法是利用了 Markdown 自身的語(yǔ)法，在 “超鏈接” 章節(jié)的內(nèi)容中提到過可以通過 「中括號(hào) []」 的方式定義全局超鏈接，而這種方式聲明的內(nèi)容不會(huì)被渲染成文字內(nèi)容輸出，因此達(dá)到了注釋的效果。

實(shí)例 3：

#### 通過 Markdown 解析達(dá)到注釋效果

[//]: (這是一段被注釋掉的文字)

這是一段沒有被注釋的文字

其渲染結(jié)果如下：

其轉(zhuǎn)換后的 html 的內(nèi)容如下：

<p>這是一段沒有被注釋的文字</p>

請(qǐng)注意：此種方法被注釋的內(nèi)容是不被渲染輸出的。

3. 使用場(chǎng)景及實(shí)例

寫作者在書寫文檔的時(shí)候難免會(huì)出現(xiàn)無法一次完成的情況，這時(shí)候?qū)⒉莞宀糠肿⑨屍饋恚梢宰屛恼略诓挥绊懽x者閱讀的情況下保持持續(xù)更新。另一方面，Markdown 仍是一種編碼語(yǔ)言，在使用過程中，尤其是團(tuán)隊(duì)協(xié)作過程中，我們可能需要一些特殊用法來實(shí)現(xiàn)想要的功能，那此時(shí)注釋就非常適合作為代碼說明。

實(shí)例 4：一段適合多人協(xié)作編輯的文檔

#### 一個(gè)適合多人編輯的文檔

### 一、前言

<!--
負(fù)責(zé)人：項(xiàng)目經(jīng)理
補(bǔ)充內(nèi)容：項(xiàng)目背景、實(shí)現(xiàn)目標(biāo)、開發(fā)周期、責(zé)任人員分配。
計(jì)劃用時(shí)：1周
-->

### 二、需求整理

<!--
負(fù)責(zé)人：架構(gòu)師
補(bǔ)充內(nèi)容：項(xiàng)目的最終需求整理，功能點(diǎn)描述，盡可能全面地體現(xiàn)重點(diǎn)和難點(diǎn)
計(jì)劃用時(shí)：1周
-->

### 三、架構(gòu)設(shè)計(jì)

<!--
負(fù)責(zé)人：架構(gòu)師
補(bǔ)充內(nèi)容：項(xiàng)目的技術(shù)選型、主體架構(gòu)、通過流程圖、E-R圖等形式體現(xiàn)。
計(jì)劃用時(shí)：2周
-->

### 四、詳細(xì)設(shè)計(jì)

<!--
負(fù)責(zé)人：技術(shù)專員、設(shè)計(jì)師
補(bǔ)充內(nèi)容：項(xiàng)目主要技術(shù)實(shí)現(xiàn)思路、UI設(shè)計(jì)等。
計(jì)劃用時(shí)：3周
-->

### 五、任務(wù)跟蹤表

<!-- 全部完成打鉤 √，休息日用斜杠 /，未按時(shí)完成部分打叉 × -->

|周數(shù)|周一|周二|周三|周四|周五|周六|周日|總結(jié)|
|---|---|---|---|---|---|---|---|---|
|第一周|√|√|√|√|√|/|/|按時(shí)完成|
|第二周|√|√|×|×|×|/|/|進(jìn)行中|
|第三周|||||||
|第四周|||||||

其渲染結(jié)果如下：

4. 小結(jié)

• 文檔越復(fù)雜，注釋的作用就越明顯；
• 文檔的注釋可以通過多種形式實(shí)現(xiàn)，推薦使用 <!-- --> 方式。