在前端开发过程中,我们常常需要将 Markdown 文档转换为静态网页。这种情况下,我们可以使用 Metalsmith,一个基于 Node.js 的静态站点生成器。在 Metalsmith 中,有一个常用的插件叫做 metalsmith-markdown,可以将 Markdown 文档转换为 HTML,但这个插件在某些情况下表现不够理想。
针对这个问题,社区中有一位开发者开发了一个名为 metalsmith-propdown 的 npm 包,它同样可以将 Markdown 文档转换为 HTML,但是比 metalsmith-markdown 更灵活,可以通过为 Markdown 文件添加属性来定制输出。
metalsmith-propdown 简介
metalsmith-propdown 是一个基于 Metalsmith 的插件,用于将 Markdown 文档转换为 HTML。它提供了一种非常灵活的方式来控制 Markdown 文档的输出,即通过在 Markdown 文件中添加属性来实现。与其它插件相比,metalsmith-propdown 支持更多的自定义选项,可以满足各种需求,例如自定义 CSS 样式和脚本等。
如果你之前有使用过 Metalsmith,对其概念应该已经比较熟悉。如果你还不熟悉 Metalsmith,可以参考 Metalsmith 官方文档 进行学习。
安装
先安装 Node.js 环境;
在终端中运行以下命令:
npm install --save metalsmith metalsmith-propdown
使用
首先,在 project 根目录下,创建一个新文件夹,并在该文件夹下创建一个 markdown 文档,例如 index.md
。
-- -------------------- ---- ------- --- ------ ---- -------- -- ------- -- ----- ---------- --- - ------ -------- -- --------- -------- ------------
然后,我们需要创建一个 metalsmith.js
文件,用于配置 Metalsmith:
-- -------------------- ---- ------- --- ---------- - ---------------------- --- -------- - ------------------------------- --------------------- ---------------- ----------------------- ---------------- -------------------- - -- ----- ----- ---- ---
在这个文件中,我们引入了 metalsmith
和 metalsmith-propdown
包,并用 use()
方法将插件添加到 Metalsmith 的构建流程中。
其中,.source()
方法用于指定源文件的位置,.destination()
方法用于指定输出文件的目标位置。在这个例子中,我们将源文件放在 ./src
,输出文件放在 ./build
。
最后,在终端中运行以下命令:
node metalsmith.js
即可在 ./build
目录下生成一个 index.html
文件。
metalsmith-propdown 属性
metalsmith-propdown 允许我们在 Markdown 文档中添加属性来控制输出。这些属性以 YAML 格式写在文档头部,用三个短横线(---
)包裹。例如:
-- -------------------- ---- ------- --- ------ ---- -------- -- ------- -- ----- ---------- --- - ------ -------- -- --------- -------- ------------
这个 Markdown 文档定义了三个属性:title
、author
和 date
。
以下是 metalsmith-propdown 支持的属性列表:
title
:指定文档标题,默认为 Markdown 文档中的第一行文本;date
:指定文档日期,默认为文件的修改日期;author
:指定文档作者;layout
:指定使用哪个布局模板,例如layout: article
;style
:指定 CSS 样式文件,例如style: styles.css
;script
:指定 JavaScript 脚本文件,例如script: main.js
。
例如,我们可以在 Markdown 文档中添加 layout
属性,指定该文档使用 article.hbs
模板:
-- -------------------- ---- ------- --- ------ ---- -------- -- ------- -- ----- ---------- ------- ------- --- - ------ -------- -- --------- -------- ------------
示例代码
为了更好地理解 metalsmith-propdown 的用法,下面给出一个完整的示例代码:
directory structure:
-- -------------------- ---- ------- - --- ------ --- ---- - --- --------- - - --- ----------- - - --- -------- - --- -------- - --- ----------- - --- ----------- --- -------------
index.md
:
--- title: My Site layout: home --- # My Site Welcome to my website!
article1.md
:
-- -------------------- ---- ------- --- ------ ------- - ------- ------- ----- ---------- --- - ------- - ---- -- --- ------- -- ------- --
article2.md
:
-- -------------------- ---- ------- --- ------ ------- - ------- ------- ----- ---------- --- - ------- - ---- -- --- ------- -- ------- --
_layouts/home.hbs
:
-- -------------------- ---- ------- --------- ----- ------ ------ ----- ---------------- --------- ----- ---------- ----- ---------------- ----------------- ------- ------ --- -------- --- ------- ------------------------- ------- -------
_layouts/article.hbs
:
-- -------------------- ---- ------- --------- ----- ------ ------ ----- ---------------- --------- ----- ---------- ----- ---------------- ----------------- ------- ------ --------- ------ ----- ------- ----- ---- ------ --- -------- --- ---------- ------- ------------------------- ------- -------
metalsmith.js
:
-- -------------------- ---- ------- --- ---------- - ---------------------- --- -------- - ------------------------------- --- --------- - -------------------------------- --- ---------- - --------------------------------- --------------------- ----------- ------ --- ----- -- ---------------- ----------------------- ------------ ---------------- ------------------ ---------------- ------- ------------- ---------- ---------------- --- -------------------- ------ - -- ----- - ----- ---- - ------------------ ------------ ---
在这个示例中,我们对 .use()
方法进行了链式调用,依次使用了:
markdown()
插件,用于将 Markdown 文档转换为 HTML;permalinks()
插件,用于为每个输出文件生成固定链接;templates()
插件,用于根据文档属性使用 Handlebars 模板来生成输出 HTML。
在实际使用中,我们可以根据需要扩展这个流程,例如增加自动化构建、文件压缩等操作。
结语
本文介绍了如何使用 npm 包 metalsmith-propdown 来将 Markdown 文档转换为静态网页。通过添加文档属性,我们可以灵活地控制输出的 HTML,例如添加 CSS 样式和脚本等。Metalsmith 是一个非常强大的静态站点生成器,如果你还不熟悉,建议你去了解一下。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/60066f411d8e776d08040d02