服务端相关 / 02 Markdown 导出 HTML

Markdown 导出 HTML

1. 前言

Markdown 的源文件以 md 为后缀。Markdown 是 HTML 语法的简化版本,它本身不带有任何样式信息。我们所看到的 Markdown 网页(如:github 里常用的 README.md 文件)、Markdown 编辑器(比如 Typora)预览的效果,其实都是将 Markdown 文档内容首先转换成 HTML 标签,再配以某些默认预定共同渲染而成的。

例如,同样的一段表格代码,在 Typora 和 VS Code 预览中的表现不同:

图片描述

为了让 Markdown 的表现形式稳定,我们可将 Markdown 导出成 HTML 文件。

2. 语法详解

2.1 使用 Typora 导出 HTML

Typora 导出 HTML 的操作方式为:

「文件」->「导出」->「HTML」

注意:导出时可以看到 HTML 和 HTML(Without Styles)两个选项,它们的区别是:

导出 HTML 时,会根据 Typora 所选主题(「菜单栏」->「主题」),导出包括扩展在内的所有内容;

导出 HTML(Without Styles)时,生成的 HTML 文件只包含 Markdown 基本语法的转换,不含任何扩展及主题样式。

例如,同样的一段表格代码,导出 HTML 和 HTML(Without Styles)的不同表现:

图片描述

一般情况下,推荐使用「导出 HTML」的方法。
除非需要重新定义样式及扩展,否则不推荐使用「导出 HTML(Without Styles)」的导出方式。

2.2 使用 Pandoc 导出 HTML

如果只有 Markdown 源文件,在不通过 Markdown 编辑器的情况下,还可以使用 Pandoc 将其直接转换成 HTML 文件。

Pandoc 是一种标记语言转换工具,可实现不同标记语言间的格式转换。

Pandoc 的安装方法参见其 Github 项目页

实例 1

使用 Pandoc 将 Markdown 转换为 Html。

pandoc in.md -o out.html

实例 2

转换时增加外部样式文件引用,如:style.css。

pandoc in.md -c style.css out.html

注意:此时输出的是一个目录。

实例 3

将所有外部文件都嵌入到单个 HTML 文件中,包括嵌入视频、图片等。

pandoc -s --self-contained -c style.css in.md -o out.html

Markdown 有一些扩展语法,比如「Mermaid」,「数学公式」等,要支持此类功能,Pandoc 也需要一些插件的支持,例如:Memaid-Filter 可用于渲染 Mermaid 图像。

3. 小结

  • Markdown 源文件只规定了显示的内容,并没有定义显示的样式,所以在不同的预览环境下会看到不同的效果。为了使其保持统一,需要将 Markdown 文件转换成 HTML 文件;
  • 常见的 Markdown 编辑器都带有导出成 HTML 的功能,导出后通常含有编辑器自带样式;
  • 利用 Pandoc,我们可以在命令行中直接将 Markdown 文件导出成 HTML 文件。