前言
Metalsmith 是一个静态网站生成器。它可以用于构建任何静态网站，包括博客、文档网站、API 文档等等。
Metalsmith 的设计非常灵活，它通过 plugin 的方式来扩展功能。你可以选择各种 plugin 来处理网站的各个方面，包括 markdown 转 html、代码压缩、图片优化等等。
metalsmith-in-place 是一个 Metalsmith 插件，它可以直接在 markdown 文件中使用模板引擎进行渲染。它的使用非常简单，本文将为大家介绍如何使用 metalsmith-in-place，以及它的一些高级使用方法。
安装 metalsmith-in-place
在使用 metalsmith-in-place 之前，需要先安装 Metalsmith 和 Node.js。
使用 npm 安装 metalsmith-in-place：
npm install metalsmith metalsmith-in-place --save-dev
基本使用方法
在使用 metalsmith-in-place 之前，需要对 Metalsmith 进行一些配置。在项目的根目录下创建一个 metalsmith.js 文件，然后编辑如下代码：
const Metalsmith = require('metalsmith'); const inPlace = require('metalsmith-in-place'); const metalsmith = Metalsmith(__dirname) .source('./src') // 源文件路径 .destination('./build'); // 输出文件路径 metalsmith.use(inPlace());
这段代码中，我们首先引入了 Metalsmith 和 metalsmith-in-place 模块，然后创建了一个 metalsmith 对象，指定源文件路径和输出文件路径。最后调用 metalsmith.use(inPlace()) 来使用 metalsmith-in-place 插件。
接下来我们在项目的 src 目录下创建一个 index.md 文件，内容如下：
--- title: My blog --- # {{title}} This is my blog.
在文件头部我们定义了一个 title 变量，然后在文本中使用了 {{title}} 进行了替换。这里的 {{title}} 由所使用的模板引擎来进行渲染。metalsmith-in-place 内置了两个渲染引擎：Handlebars 和 Hogan.js。我们可以在插件参数中指定所使用的引擎，默认是 Handlebars。
现在我们可以在命令行执行 node metalsmith.js 命令，在 build 目录下就会生成渲染后的 HTML 文件。
参数配置
在使用 metalsmith-in-place 时，可以指定一些参数来控制其行为。例如，我们可以使用 engine 参数来指定所使用的模板引擎，还可以使用 pattern 参数来指定要匹配的文件。
engine
engine 参数用于指定模板引擎。默认情况下，metalsmith-in-place 使用的是 Handlebars 引擎，但是你可以使用其他支持模板引擎的库，例如 Twig、Pug 等。
在这个示例中，我们将使用 Pug 引擎。
首先需要安装 pug：
npm install pug --save-dev
然后修改 metalsmith.js 文件如下：
-- -------------------- ---- ------- ----- ---------- - ---------------------- ----- ------- - ------------------------------- ----- ---------- - --------------------- ---------------- ------------------------ --------------- --------- ------- ------ --- --展开代码
现在我们可以在 src 目录下创建一个 test.pug 文件，内容如下：
h1= title p This is a test.
然后在 index.md 文件中使用以下内容：
--- title: Test --- != pug('test.pug')
注意这里使用了 != 语法，它会直接将 Pug 模板渲染成的 HTML 插入到文本中。这里的 pug 函数是在插件中自动生成的。其实这里的 pug 函数就是 pug.render 函数的封装。如果需要传递变量给模板，可以这样写：
--- title: Test --- != pug('test.pug', { message: 'Hello world!' })
然后在 test.pug 文件中使用以下内容：
h1= title p= message
pattern
pattern 参数用于指定所匹配的文件。默认情况下，只有后缀为 .html 的文件才会被处理。你可以使用正则表达式或函数来指定要处理哪些文件。
我们来看一个示例，在项目的 src 目录下创建一个 about.md 文件，然后编辑如下内容：
# About page然后修改 metalsmith.js 文件如下：
-- -------------------- ---- ------- ----- ---------- - ---------------------- ----- ------- - ------------------------------- ----- ---------- - --------------------- ---------------- ------------------------ --------------- --------- -------- ---------- -- ---- --- -- --- --展开代码
现在我们执行 node metalsmith.js 命令，就可以看到生成了 about.html 文件。
高级使用
在实际开发中，我们可能需要更复杂的功能，例如在 markdown 文件中使用标签、自定义标签等。这时候，metalsmith-in-place 就提供了一些高级使用方式。
在 markdown 中使用标签
metalsmith-in-place 支持在 markdown 文件中使用标签。这里的标签可以是任何 HTML 标签，例如 div、p、img 等等。当 markdown 文件被渲染时，metalsmith-in-place 会将标签转换为 HTML。
我们来看一个示例，在 index.md 文件中使用以下内容：
-- -------------------- ---- ------- --- ------ -- ---- --- - --------- ---- -- -- ----- ----- ------------- ------------ ----------展开代码
我们在 markdown 中使用了一个 span 标签，并指定了其颜色为红色。当 Markdown 文件被渲染时，这个标签会被转换为 HTML。
自定义标签
有时候，我们需要更强大的功能，例如在 markdown 文件中使用代码高亮等功能。这时候，我们可以自定义标签，来对其进行处理。
metalsmith-in-place 支持自定义标签。你可以使用 registerTag 方法注册一个标签处理器。标签处理器有两个回调函数：open 和 close。当遇到一个标签时，open 回调函数会被调用；当标签结束时，close 回调函数会被调用。
下面是一个使用自定义标签的示例。我们将引入一个名为 highlight 的库，可以实现代码高亮的功能。
首先需要安装 highlight：
npm install highlight.js --save-dev
然后修改 metalsmith.js 文件如下：
-- -------------------- ---- ------- ----- ---------- - ---------------------- ----- ------- - ------------------------------- ----- ---- - ------------------------ ---------------- ---------- -------------- ------ -------- --- -- -- ---- -- --------------------------- ------ -------- -- - ----- ---- - ------- -- ------------- -- ------------- ---------- ----- ----------- - -------------------- --------------- ------ ----------- ----------- -------------------------------------- --- ----- ---------- - --------------------- ---------------- ------------------------ --------------- --------- -------- ---------- --- --展开代码
在这个示例中，我们先引入了 highlight 和 metalsmith-in-place，然后使用 hljs.configure 方法配置 hljs，这里我们仅加入了三个语言：JavaScript、CSS、HTML。
然后我们使用 inPlace.registerTag 方法，注册了一个名为 hljs 的标签，用于处理代码高亮。在 registerTag 的第一个参数中传入了标签的名称，第二个参数是一个回调函数，当遇到 hljs 标签时，这个回调函数就会被调用。在这个示例中，我们使用了 hljs.highlight 方法对代码进行了高亮，并将其插入到了 HTML 代码块中。
现在我们可以在 index.md 中使用以下代码：
-- -------------------- ---- ------- --- ------ -- ---- --- - --------- ---- -- -- ----- --- ---- ---------- -------- --- -- - ------ - - -- - ---展开代码
这里使用了自定义标签 hljs，并设置了其语言为 javascript。当 markdown 被渲染时，hljs 标签会被自定义的处理器处理，最后生成带有代码高亮的 HTML。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65896
