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. 小结
- 文档越复杂,注释的作用就越明显;
- 文档的注释可以通过多种形式实现,推荐使用
<!-- -->
方式。
- 还没有人评论,欢迎说说您的想法!