npm 包 metalsmith-propdown 使用教程

阅读时长 8 分钟读完

在前端开发过程中,我们常常需要将 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 官方文档 进行学习。

安装

  1. 先安装 Node.js 环境;

  2. 在终端中运行以下命令:

使用

首先,在 project 根目录下,创建一个新文件夹,并在该文件夹下创建一个 markdown 文档,例如 index.md

-- -------------------- ---- -------
---
------ ---- -------- --
------- --
----- ----------
---

- ------ -------- --

--------- -------- ------------

然后,我们需要创建一个 metalsmith.js 文件,用于配置 Metalsmith:

-- -------------------- ---- -------
--- ---------- - ----------------------
--- -------- - -------------------------------

---------------------
  ----------------
  -----------------------
  ----------------
  -------------------- -
    -- ----- ----- ----
  ---

在这个文件中,我们引入了 metalsmithmetalsmith-propdown 包,并用 use() 方法将插件添加到 Metalsmith 的构建流程中。

其中,.source() 方法用于指定源文件的位置,.destination() 方法用于指定输出文件的目标位置。在这个例子中,我们将源文件放在 ./src,输出文件放在 ./build

最后,在终端中运行以下命令:

即可在 ./build 目录下生成一个 index.html 文件。

metalsmith-propdown 属性

metalsmith-propdown 允许我们在 Markdown 文档中添加属性来控制输出。这些属性以 YAML 格式写在文档头部,用三个短横线(---)包裹。例如:

-- -------------------- ---- -------
---
------ ---- -------- --
------- --
----- ----------
---

- ------ -------- --

--------- -------- ------------

这个 Markdown 文档定义了三个属性:titleauthordate

以下是 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:

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

纠错
反馈