服务端相关 / 19 Markdown 注释

Markdown 注释

1. 前言

在任何一款现代程序语言中,注释都是至关重要的,它是源代码文件提升可读性的重要补充,也是多人协作时的重要工具。

Markdown 的注释可以通过三种方法实现:第一是通过 html 的 <!-- --> 标记;第二可以通过样式隐藏段落内容,即 <div style="display:none">;第三是通过 Markdown 自身的解析原理实现。

环境说明
考虑到 Markdown 工具之间的不兼容,有的内容直接从页面复制粘贴到本地不会正常显示,大家学习时自己动手写是肯定没问题的。本节所有实例代码及演示效果均使用 Typora 工具完成。
本节所有截图均为 Typora 导出 HTML 后网页的渲染效果。

2. 语法详解

2.1 使用原生 HTML 注释语法

因为 Markdown 文档是基于 HTML 实现的,所以可以通过 HTML 原生对注释的支持实现文档注释效果。

实例 1

#### 基于 HTML 标签的注释

<!-- 这是一段被注释掉的文字 -->

这是一段没有被注释的文字

其渲染结果如下:

图片描述

其转换后的 html 的内容如下:

<p>这是一段没有被注释的文字</p>

请注意:此种方法被注释的内容是不被渲染输出的。

2.2 使用 HTML 样式实现隐藏

这种方式原则上并不是注释,而是将内容隐藏,已达到注释效果。

实例 2

#### 基于 HTML 样式

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

这是一段没有被注释的文字

其渲染结果如下:

图片描述

其转换后的 html 的内容如下:

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

<p>这是一段没有被注释的文字</p>

请注意:此种方法被注释的内容是会被渲染输出的,只是在输出时会被隐藏。

2.3 通过 Markdown 自身的解析功能

这种方法是利用了 Markdown 自身的语法,在 “超链接” 章节的内容中提到过可以通过 「中括号 []」 的方式定义全局超链接,而这种方式声明的内容不会被渲染成文字内容输出,因此达到了注释的效果。

实例 3

#### 通过 Markdown 解析达到注释效果

[//]: (这是一段被注释掉的文字)

这是一段没有被注释的文字

其渲染结果如下:

图片描述

其转换后的 html 的内容如下:

<p>这是一段没有被注释的文字</p>

请注意:此种方法被注释的内容是不被渲染输出的。

3. 使用场景及实例

写作者在书写文档的时候难免会出现无法一次完成的情况,这时候将草稿部分注释起来,可以让文章在不影响读者阅读的情况下保持持续更新。另一方面,Markdown 仍是一种编码语言,在使用过程中,尤其是团队协作过程中,我们可能需要一些特殊用法来实现想要的功能,那此时注释就非常适合作为代码说明。

实例 4:一段适合多人协作编辑的文档

#### 一个适合多人编辑的文档

### 一、前言

<!--
负责人:项目经理
补充内容:项目背景、实现目标、开发周期、责任人员分配。
计划用时:1周
-->

### 二、需求整理

<!--
负责人:架构师
补充内容:项目的最终需求整理,功能点描述,尽可能全面地体现重点和难点
计划用时:1周
-->

### 三、架构设计

<!--
负责人:架构师
补充内容:项目的技术选型、主体架构、通过流程图、E-R图等形式体现。
计划用时:2周
-->

### 四、详细设计

<!--
负责人:技术专员、设计师
补充内容:项目主要技术实现思路、UI设计等。
计划用时:3周
-->

### 五、任务跟踪表

<!-- 全部完成打钩 √,休息日用斜杠 /,未按时完成部分打叉 × -->

|周数|周一|周二|周三|周四|周五|周六|周日|总结|
|---|---|---|---|---|---|---|---|---|
|第一周|√|√|√|√|√|/|/|按时完成|
|第二周|√|√|×|×|×|/|/|进行中|
|第三周|||||||
|第四周|||||||

其渲染结果如下:

图片描述

4. 小结

  • 文档越复杂,注释的作用就越明显;
  • 文档的注释可以通过多种形式实现,推荐使用 <!-- --> 方式。