您好, 欢迎来到 !    登录 | 注册 | | 设为首页 | 收藏本站

Markdown 注释

1. 前言

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

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

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

2. 语法详解

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

实例 1

#### 基于 HTML 的注释<!-- 这是一段被注释掉的 -->这是一段没有被注释的

其渲染结果如下:

其转换后的 html 的如下:

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

请注意:此种被注释的是不被渲染的。

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

实例 2

#### 基于 HTML 样式<div style="display:none">这是一段被注释掉的</div>这是一段没有被注释的

其渲染结果如下:

其转换后的 html 的如下:

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

请注意:此种被注释的是会被渲染的,只是在时会被隐藏。

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

实例 3

#### 通过 Markdown 解析达到注释[//]: (这是一段被注释掉的)这是一段没有被注释的

其渲染结果如下:

其转换后的 html 的如下:

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

请注意:此种被注释的是不被渲染的。

3. 使用场景及实例

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

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

#### 适合多人编辑的文档### 一、前言<!--
负责人:项目经理
补充:项目背景、实现目标、开发周期、责任人员分配。
计划用时:1周
-->### 二、需求整理<!--
负责人:架构师
补充:项目的最终需求整理,点描述,尽可能全面地体现重点和难点
计划用时:1周
-->### 三、架构设计<!--
负责人:架构师
补充:项目的技术选型、主体架构、通过流程图、E-R图等形式体现。
计划用时:2周
-->### 四、详细设计<!--
负责人:技术专员、设计师
补充:项目主要技术实现思路、UI设计等。
计划用时:3周
-->### 五、任务跟踪表<!-- 全部完成打钩 √,休息日用斜杠 /,未按时完成部分打叉 × -->|周数|周一|周二|周三|周四|周五|周六|周日|总结|
|---|---|---|---|---|---|---|---|---|
|第一周|√|√|√|√|√|/|/|按时完成|
|第二周|√|√|×|×|×|/|/|进行中|
|第三周|||||||
|第四周|||||||

其渲染结果如下:

4. 小结

文档越复杂,注释的作用就越明显;

文档的注释可以通过多种形式实现,推荐使用 <!-- --> 方式。


联系我
置顶