集美大学 计算机 郑如滨

教学博客

  博客园 :: 首页 :: 博问 :: 闪存 :: 新随笔 :: 联系 :: 订阅 订阅 :: 管理 ::

拓展阅读:使用Markdown编写文档

本文博客链接

1. 引子

人们在开发软件的时候,经常需要编写文档。最早期的时候,文档就是使用最简单的文本格式编写的,比如txt文件。那时候的软件说明文档文件名通常为ReadMe.txt,人们随便使用一个简单文本编辑器就可以查看。然而,简单的文本文件不支持任何格式,比如标题、列表、图片等等,这给阅读和分享带来了很大的不便。

后来,人们尝试使用一些专用软件,如Word,来编写软件说明文档。然而,这些专用软件虽然功能强大,但需要付费,有时还需要专用软件才能打开,不利于文档的传播。而且对于使用者来说,学会专用软件编写文档本身就需要耗费一定的精力。另外一个显著的缺点就是,这种文档虽然支持丰富的格式,但因为没有统一的格式规范,导致不同人编写的文档格式差异很大。这使得,即使是在同一个项目中,文档的格式也可能千差万别,那么全世界不同开发者为不同项目编写的文档更是千差万别。这非常不利于文档的传播和维护。

2. Markdown简介与应用

2.1 Markdown是什么?

Markdown是一种可以使用普通文本编辑器编写标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。Markdown编写的文档可以导出HTML、PDF等多种格式的文档。并且由于有着统一的格式规范,使得即使是不同的人编写的Markdown文档,也能在几乎所有Markdown解析器上正确显示。这使得Markdown文档可以被非常广泛地传播和使用。本篇文章就是使用Markdown所编写。

2.2 Markdown的应用

在计算机行业,Markdown有着广泛的应用。包括但不限于如下几种:

  1. 代码管理站上项目的说明文档
  2. 博客编写
  3. 技术文档编写
  • 示例:代码管理站上项目的说明文档
    GitHub是一个著名的代码管理站,上的很多开源项目都提供了Markdown格式的文档,比如,打开openjdk在GitHub上的项目主页,可以看到如下图所示页面:

    红色方框框起来的就是README.md文件,这个文件就是使用Markdown编写的。箭头所指的区域就是GitHub对Markdown格式的文档所作的渲染,可以看到,这个文档被渲染成了一个比较美观的网页。
  • 示例:博客文档
    除了代码管理站点GitHub之外,还有很多博客网站也支持使用Markdown格式编写博客。比如国内的博客园、CSDN博客、简书等。
    作者的教学博客上的绝大部分文章也使用了Markdown编写。下图为作者的一篇使用Makrdown编写的博客文章页面:

    这个页面对应的部分Markdown文本如下所示:

    图片中的[TOC] ** # - []()等就是Markdown标记。

3. 学习Markdown

初学者应掌握Markdown的一些基本概念,如基本的格式符号、常用的标记语法和一些常用工具。

3.1 Markdown的相关工具

支持Markdown的工具与服务种类繁多,包括:

  1. 本地文本编辑器:如TyporaVSCode(需要安装Markdown插件)等。
  2. 在线Markdown编辑器:如StackEditCmd Markdown等。
  3. 支持Markdown的博客:博客园、CSDN、简书等。
  4. 支持Markdown的代码管理站点:如GitHub、Gitee等。
  5. 支持文档转换的软件:如Pandoc等。

建议:

  1. 编写:作为初学者可以先直接使用在线Markdown编辑器试水,熟悉Markdown语法后,再使用本地文本编辑器编写Markdown文档。
  2. 文档格式转换:有的本地编辑器通过安装插件,可以很方便的将Markdown文本文件转换成HTML格式,并直接在浏览器中预览效果,还有的插件甚至可以直接将Markdown文本转换成PDF格式。
  3. 编写博客:直接找一个支持Markdown的博客网站即可。前面列举的博客网站均支持Markdown格式,并提供预览功能。

3.2 基本概念与标记符号

Markdown虽然以简单著称,但作为初学者,还是需要掌握一些基本概念与简单标记。

3.2.1 基本概念

  • 标记符号
    Markdown文本中使用的特殊符号。编写文本时使用某些标记符号,渲染工具会将其转换成HTML格式。
  • 文件扩展名
    Makrdown文件的扩展名为.md
  • 渲染
    指的是将Markdown文本转换为最终可视化输出的过程。这包括将Markdown文本解析并转换为HTML、PDF、Word等格式,以便用户能够查看或分享最终呈现的文档。渲染这个概念是Markdown的核心概念,也是Markdown与其它格式文档最大的区别。
  • 图床
    Makrdown文件为纯文本文件,无法放置图片只能放置图片的文本链接。图片本身要么被存放在本机(比如与.md文件相同的目录),要么存放在网络上的某个服务器并能通过网络链接访问。这个专门用来存放图片的服务器称为图床。不过通常编写网络文章(比如博客),博客网站都会提供存放图片的方法,编写者无需操心图片的存储问题。
  • 方言(Dialect)
    指基于Markdown语法的扩展或变种,如GitHub Flavored Markdown(GFM)、CommonMark等。这些方言在原始Markdown语法的基础上添加了额外的功能或规范,以满足特定需求或提供更丰富的功能。初学者只需使用原始的Markdown语法即可,无需了解其它方言。

3.2.2 基本的标记符号

可以将Markdown编写的文本理解成一个代码文件,其中包含一些特殊的标记符号。渲染工具会将这些标记符号转换成HTML格式,并将其显示在网页上。因此,编写者需要掌握基本的标记符号。常用的标记符号有:

  1. 标题:使用#标记不同级别的标题,#的个数代表了标题的级别,#的个数不能超过6个。通常Markdown文章的第一行放置一级标题(使用一个#标记),作为文章名称。
  2. 段落:使用一个或多个空行分隔多个段落。通常Markdown文本的段落行首不需要缩进(简单的讲,不需要加空格)。
  3. 换行:使用两个空格加回车符(<Enter>)实现换行。
  4. 字体:使用一对**或一对*标记粗体和斜体。
  5. 列表:使用-标记无序列表,使用数字.标记有序列表,如1.。注意-数字.后应有一个空格。
  6. 链接:使用[]()标记链接,其中[]中的内容为链接的标题,()中的内容为链接的URL地址。
  7. 图片:使用![图片标题](图片URL地址)标记图片,其中[]中的内容为图片的标题,()中的内容为图片的URL地址。
  8. 代码:使用一对```标记将代码块(多行代码)标记出来。使用一对`标记行内代码。
  9. 分隔线:使用三个或以上的*-标记分隔线。
  10. 引用:使用>标记引用内容。
  11. 表格:相对比较复杂,可以借助所使用的编辑器中的插入表格功能实现。

Markdown编写建议:

  1. 初学者掌握可先重点掌握标记中的1-4快速上手,然后再逐步掌握5-10,需要的时候再去查看11。
  2. Markdown还包含支持画图的标记,不过使用起来相对比较繁琐,建议可以使用其他画图工具画好以后截图,然后将截图粘贴到Markdown文本中。
  3. 有的时候,Markdown文本无法正常渲染某些标记,可尝试在其他标记符号后加一个或两个空格,或者在段落之间加一个空行。
  4. 在本地写好的Markdown文本,粘贴到博客网站后应预览检查一下,确保渲染后的效果符合预期。比如,图片链接是否正确,个别标记能否渲染成功等。

3.2.3 一个Markdown文档示例

现在编写一个Markdown文档,用来说明一个Java版本的HelloWorld代码,大家可通过此文档学习Markdown的基本标记符号与语法。

底下分割线内的为所要演示的Markdown文本渲染后的结果及相关截图。


一、Markdown文本渲染后的结果

本文将演示如何使用Markdown编写一个技术文档,用来说明一个Java版本的HelloWorld。

1. Java版本的HelloWorld代码:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

2. 如何运行:

  1. 下载并安装JDK,并配置环境变量。
  2. 在Windows下使用CMD命令,打开控制台。
  3. 在控制台输入javac HelloWorld.java,如果未提示异常信息,则表示编译成功。
  4. 输入java HelloWorld,如果控制台输出Hello, World!,则表示运行成功。

3. 运行结果截图:

4. 代码说明:

  • public class HelloWorld:定义了一个名为HelloWorld的类。
  • public static void main(String[] args):定义了一个名为main的静态方法。
  • System.out.println("Hello, World!"):向控制台输出字符串"Hello, World!"。

5. 与C语言版本的HelloWorld代码的比较:

特性 C语言版本HelloWorld代码 Java语言版本HelloWorld代码
文件扩展名 .c .java,
有无启动虚拟机
跨平台运行 不支持 支持
接收命令行参数 通过arc、argv参数 通过String[] args参数
输出命令代码 printf System.out.println

二、上述渲染结果对应的Markdown文本截图


4. Markdown流行的原因

Markdown的流行主要得益于几个方面:

  • 语法简单、格式开放与统一
    语法简单使得任何人都可以快速掌握并编写出符合要求的文档;格式开放使得任何人只需使用最简单的文本编辑器就可以使用Markdown编写包含丰富格式的文档;格式统一指的是无论使用何种Markdown方言,其支持的基本语法与标记都是相同的,且渲染效果也是大同小异,这使得Markdown编写者可以轻松看懂、编辑其他人的Markdown文档,并且总是能得到预期中的文档渲染效果。
  • 支持协作
    Markdown文件因为是纯文本文件,所以可以通过版本控制系统(如Git)进行版本控制和协作编辑,使得团队可以轻松地共享和协作编写文档。而当今的项目(无论是开源还是非开源)往往需要多人共同参与,那么支持版本控制的Markdown文本于是成为了项目文档撰写的首选。
  • 易于分享
    Markdown文章可以轻松地分享给他人。无论是代码管理系统(如GitHub)还是大量的博客平台,他们均支持Markdown文本的解析和渲染。那么使用Markdown编写的文档可以轻松地发布到互联网上,供他人阅读和评论。
  • 开源工具支持
    有许多开源工具和库支持Markdown。例如,Pandoc支持Markdown到多种其他格式文档的转换,Typora支持Markdown的实时预览和编辑。这些工具进一步促进了Markdown的开放性和可访问性。

综上所述,Markdown之所以流行,是因为它简单高效、适合团队协作、易于分享和易于使用,这些特点背后蕴含了实用主义、团队精神和开放共享等思想。正如中国古语所说:“工欲善其事,必先利其器。”Markdown作为一种简单高效的工具,体现了实用主义的原则,通过“少即是多”的思路提高了文档撰写的效率。同时,“众人拾柴火焰高”,Markdown支持团队协作的特性彰显了团队精神的重要性,它让集体智慧得以汇聚和放大。再者,“独学而无友,则孤陋而寡闻”,Markdown的开放共享理念使得知识分享更加便捷,有助于促进信息流通和知识普惠。通过推广和使用Markdown及其相关的开源工具,我们相信,Markdown将继续引领下一代文档撰写和分享方式,为人类的知识传播和科技创新做出更大的贡献。

思考与练习

  1. 尝试使用Markdown为你的项目撰写一篇博客文章,并发布到互联网上。其中应包含标题、特殊字体、代码、列表等标记。
  2. 尝试使用本地的Markdown编辑器编写一篇Markdown文档。
  3. 尝试将Markdown文档转换为其他格式文档,如PDF、Word等。
posted on 2024-03-18 10:47  zhrb  阅读(90)  评论(0编辑  收藏  举报