开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载本篇文章以仓库中 examples/static-site 示例项目 的首页文件 src/index.md 为切入点完整讲解如何用 Metalsmith 从一篇带 frontmatter 的 Markdown 文档出发经过插件流水线加工最终渲染出一个带博客文章列表的静态首页。读完本文你将掌握 frontmatter 字段title/layout/postlist的含义与解析原理、collectionspermalinkslayouts三个插件在构建链中的协作方式以及整个静态站点从源码到build目录的完整构建流程并能在本地直接运行该示例验证效果。一、示例项目概览static-site 是什么static-site是 Metalsmith 官方仓库中的一个经典示例目标是用极少的代码搭建一个「静态站点 博客」首页展示站点标题和全部博客文章的链接每篇博客文章拥有自己的独立页面。整个示例的目录结构如下examples/static-site/ ├── index.js # 构建脚本Metalsmith 流水线配置 ├── package.json # 依赖与 npm 脚本 ├── README.md # 运行说明 ├── layouts/ │ ├── layout.hbs # 站点通用布局首页 / 关于页使用 │ └── post.hbs # 博客文章布局 └── src/ ├── about.md # 关于页 ├── index.md # 站点首页本篇文章的主角 ├── css/ │ └── style.css # 静态样式 └── posts/ ├── first-post.md ├── second-post.md ├── third-post.md └── fourth-post.md运行方式记录在 examples/static-site/README.md 中先安装依赖再启动构建最后用静态服务器预览npm install npm start # 等价于 node index.js执行构建 npm run serve # 等价于 serve build在本机预览 build 目录依赖清单见 examples/static-site/package.json核心是metalsmith^2.5.0配以metalsmith/markdown、metalsmith/layouts、metalsmith/permalinks、metalsmith/collections四个官方插件模板引擎由jstransformer-handlebars提供开发依赖serve用于本地预览。二、首页文档逐行解读frontmatter 驱动一切本篇文章的核心文档是 src/index.md全文如下--- title: Hello World layout: layout.hbs postlist: true --- This site is about saying »Hello« to the world. # Blog Read what else I have to say. Here are all my blog posts. Enjoy reading!这是一份典型的「带 YAML frontmatter 的 Markdown」文档。以---为分隔符包裹的头部称为 frontmatter它定义了这篇文章页面的元数据分隔符之下的正文则是页面内容。对 Metalsmith 而言frontmatter 中的每个键都会成为该文件对象的属性供插件与模板读取title: Hello World——页面的标题在布局模板中通过{{ title }}输出layout: layout.hbs——指定渲染本页使用的布局模板layouts插件据此在layouts/目录中查找对应模板postlist: true——这是一个自定义的布尔开关首页布局 layout.hbs 中通过{{#if postlist}}判断是否渲染博客文章列表。正文中# Blog之后的内容是「欢迎语」之后向访问者展示博客列表的引导文案。frontmatter 解析的底层实现前端所见即所得的字段解析在核心库中由 lib/matter.js 完成。它基于gray-matter封装默认配置lib/matter.js为YAML 语言、---分隔符、不启用摘要提取。其parse方法lib/matter.js将文件内容拆成两部分解析出的 frontmatter 数据如title、layout、postlist被合并进文件对象剩余正文被包装为Buffer存入contents字段。读取文件时lib/index.js 的readFile会先判断是否开启 frontmatter默认开启见 lib/index.js以及文件是否为 UTF-8 编码然后调用matter.parse。若 frontmatter 语法非法会抛出invalid_frontmatter错误lib/index.js。仓库中的测试夹具 test/fixtures/read-frontmatter/src/index.md内容仅thing: true和 test/fixtures/read-frontmatter/src/json.mdJSON 格式 frontmatter验证了多种 frontmatter 形态的解析能力。三、构建流水线index.js 中的插件链首页index.md最终如何变成 HTML答案在 examples/static-site/index.js 这条流水线里。它演示了 Metalsmith 链式 API 的典型用法const Metalsmith require(metalsmith) const markdown require(metalsmith/markdown) const layouts require(metalsmith/layouts) const permalinks require(metalsmith/permalinks) const collections require(metalsmith/collections) Metalsmith(__dirname) .metadata({ sitename: My Static Site Blog, description: Its about saying »Hello« to the World., generator: Metalsmith, url: https://metalsmith.io/ }) .source(./src) .destination(./build) .clean(true) .use( collections({ posts: posts/*.md }) ) .use(markdown()) .use(permalinks()) .use( layouts({ engineOptions: { helpers: { formattedDate: function (date) { return new Date(date).toLocaleDateString() } } } }) ) .build(function (err, files) { if (err) throw err })3.1 全局配置方法Metalsmith(__dirname)以示例项目目录为工作目录。核心构造函数 lib/index.js 会在此初始化默认值源目录src、目标目录build、并发数Infinity、clean(true)、frontmatter(true).metadata({...})注入全局元数据lib/index.js 实现采用Object.assign合并。这里注册了sitename、description、generator、url四个键它们不挂载在单个文件上而是对所有模板全局可见——首页和文章页的页头、页脚都靠它们填充.source(./src)/.destination(./build)指定源目录与输出目录lib/index.js.clean(true)每次构建前清空目标目录lib/index.js保证build目录与最新源码严格一致。3.2 插件链四步加工collections({ posts: posts/*.md })把源目录中匹配posts/*.md的所有文章聚合成一个名为posts的集合写入全局 metadata供模板以{{#each posts}}遍历。这就是首页「博客列表」的数据来源——index.md中的postlist: true正是触发该渲染的开关。markdown()把所有.md文件的contents从 Markdown 转成 HTML。index.md正文中的# Blog标题会在此步骤变成h1Blog/h1。permalinks()把文章路径重写为目录索引形式的永久链接如first-post.md→first-post/index.html并为文件注入path属性供模板中/{{ path }}这类链接使用。仓库中 examples/jekyll 的 _site 输出 即展示了这种目录形态的构建结果。layouts({ engineOptions: { helpers: {...} } })根据每个文件 frontmatter 的layout字段在layouts/目录查找对应模板layout.hbs或post.hbs完成渲染。engineOptions.helpers向模板引擎注册自定义辅助函数formattedDate用于把文章 frontmatter 中的日期格式化为本地化日期字符串。3.3 构建流程的底层调用链build()lib/index.js是流水线的总入口其内部调用链为build→process→readrun→writereadlib/index.js递归读取源目录所有文件逐个执行 frontmatter 解析runlib/index.js借助ware中间件栈按注册顺序依次调用插件——这正是.use()lib/index.js压入this.plugins数组的执行队列writelib/index.js以可配置的并发度把处理后的文件写入目标目录。clean(true)时会在写入前先清空目标目录lib/index.js确保输出纯净。build同时支持回调与 Promise 两种形态lib/index.js本示例采用回调形式出错即throw err。四、布局模板首页与文章页如何渲染4.1 通用布局 layout.hbs首页使用的 layouts/layout.hbs 结构如下关键部分title{{ sitename }} mdash; {{ title }}/title meta namedescription content{{ description }} ... {{ sitename }} | a href/Home/a | a href/aboutAbout/a h1{{ title }}/h1 main {{{ contents }}} {{#if postlist}} ul {{#each posts}} lia href/{{ path }}{{ title }}/a/li {{/each}} /ul {{/if}} /main footer pGenerated with {{ generator }} mdash; a href{{ url }}{{ url }}/a/p /footer对照index.md的 frontmatter可以清晰看到模板变量与文档字段的对应关系{{ title }}←title: Hello World{{{ contents }}}← 分隔符下方的正文三花括号表示不转义保证h1等 HTML 原样输出{{#if postlist}} ... {{#each posts}} ... {{/each}} {{/if}}←postlist: true开启博客列表渲染遍历collections插件生成的posts集合用每篇文章的{{ title }}和{{ path }}生成列表项{{ sitename }}、{{ description }}、{{ generator }}、{{ url }}← 来自index.js中.metadata()注入的全局元数据。需要说明的是collections在permalinks之前执行而集合中保存的是对文件对象的引用因此当后续permalinks为文章补充path属性时列表渲染时即可拿到最终的永久链接路径。4.2 文章布局 post.hbs博客文章使用的 layouts/post.hbs 与通用布局结构相似区别在于标题行增加了日期输出h1{{ title }}time classfloat-right{{ formattedDate date }}/time/h1{{ formattedDate date }}调用的正是index.js中注册的 helpernew Date(date).toLocaleDateString()。文章 frontmatter 中的date: 2012-08-20经 frontmatter 解析后由gray-matter转为日期对象helper 再将其格式化为本地日期字符串。五、博客文章与关于页frontmatter 的更多实践src/posts/下的四篇文章展示了「文章型文档」的 frontmatter 写法以 first-post.md 为例--- title: My First Post date: 2012-08-20 layout: post.hbs --- An interesting post about how its going to be different this time around. Im going to write a lot more nowadays and use this blog to improve my writing.与首页相比文章多了一个date字段供formattedDate使用layout指向post.hbstitle用于页面标题与列表展示。其余三篇 second-post.md、third-post.md、fourth-post.md 结构完全一致仅标题、日期与正文不同——它们会被collections({ posts: posts/*.md })一并收集按序出现在首页的博客列表中。关于页 about.md 则展示了另一种字段组合layout: layout.hbs、title: About并显式设置description: 以覆盖全局 description。由于它不含postlist字段渲染时{{#if postlist}}判断为假不会输出博客列表。样式文件 src/css/style.css 定义了.container、header、footer、main、time等基础样式与 Bootstrap 4 一起构成页面的视觉效果同时印证了「Markdown 内容 模板 静态资源」三者分离的站点组织方式。六、本地运行与验证按 README 的指引在示例目录执行npm install npm start构建完成后build/目录中会出现首页index.html、about/index.html以及first-post/index.html等文章页面permalinks()默认的目录索引形式。接着运行npm run serve浏览器打开serve输出的本地地址即可看到首页头部展示My Static Site Blog与Hello World标题正文包含「Hello」欢迎语和# Blog区块下方是由postlist: true驱动的四篇博客文章列表点击任意链接进入对应文章页标题旁会显示formattedDate格式化后的发布日期。整条链路验证了 frontmatter → 插件流水线 → 模板渲染 → 静态输出的完整闭环。七、延伸从示例到真实站点理解了这个最小示例就能顺理成章地扩展出更完整的站点能力草稿机制仿照仓库中 drafts 插件示例 的写法——插件接收files对象删除带draft标记的文件——在流水线最前面挂一个自定义插件即可实现「未发布文章不输出」CLI 配置方式本示例使用 JS APIindex.js而 examples/jekyll 示例 展示了等价地以metalsmith.json 命令行metalsmith构建的方式根目录 README.md 中给出了两种写法的完整对照JSON 里同样支持source、destination、clean、metadata与插件列表调试手段构建卡住时可按 README.md 的建议设置DEBUG环境变量查看插件级日志。总而言之static-site示例以index.md首页为核心用不到 40 行的index.js串起 collections、markdown、permalinks、layouts 四个插件完整展示了 Metalsmith「一切皆插件、链式组装」的设计哲学。对照 lib/index.js 与 lib/matter.js 的源码还能进一步看清 frontmatter 解析、插件栈执行与文件读写等底层机制为编写自己的插件和定制构建流程打下坚实基础。赞分享开发工具CLI前端【免费下载链接】metalsmithAn extremely simple, pluggable static site generator for Node.js项目地址https://gitcode.com/gh_mirrors/me/metalsmith点击查看免费下载相关推荐深入解读 json-render No-AI 示例纯静态 Spec 的客户端渲染实战深入解读 json render No AI 示例纯静态 Spec 的客户端渲染实战 本篇技术指南以仓库中 examples/no ai 示例为核心讲解 j人工智能AI 应用前端MCP 服务Metalsmith 仿 Jekyll 构建静态博客从一篇带 frontmatter 的 Markdown 文章说起Metalsmith 仿 Jekyll 构建静态博客从一篇带 frontmatter 的 Markdown 文章说起 本篇以 Metalsmith 仓库自带的开发工具CLI前端ngx-bootstrap Progressbar 静态示例Static深入解析value、type、striped 与 animate 参数实战ngx bootstrap Progressbar 静态示例Static深入解析value、type、striped 与 animate 参数实战 导读UI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考