[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-10193":3},{"id":4,"name":5,"fullName":6,"owner":5,"repo":5,"description":7,"homepage":8,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":15,"starSnapshotCount":15,"syncStatus":17,"lastSyncTime":35,"discoverSource":36},10193,"metalsmith","metalsmith\u002Fmetalsmith","An extremely simple, pluggable static site generator for Node.js","https:\u002F\u002Fmetalsmith.io",null,"JavaScript",7829,609,97,19,0,1,2,3,67.56,"MIT License",false,"master",true,[25,26,27,5,28,29,30,31],"javascript","markdown","markdown-to-html","nodejs","ssg","static-site-generator","templates","2026-06-12 04:00:49","# Metalsmith\n\n[![npm: version][npm-badge]][npm-url]\n[![ci: build][ci-badge]][ci-url]\n[![code coverage][codecov-badge]][codecov-url]\n[![license: MIT][license-badge]][license-url]\n[![Gitter chat][gitter-badge]][gitter-url]\n\n> An extremely simple, _pluggable_ static site generator for NodeJS.\n\nIn Metalsmith, all of the logic is handled by plugins. You simply chain them together.\n\nHere's what the simplest blog looks like:\n\n```js\nimport { fileURLToPath } from 'node:url'\nimport { dirname } from 'path'\nimport Metalsmith from 'metalsmith'\nimport layouts from '@metalsmith\u002Flayouts'\nimport markdown from '@metalsmith\u002Fmarkdown'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\n\nMetalsmith(__dirname)\n  .use(markdown())\n  .use(\n    layouts({\n      pattern: '**\u002F*.html'\n    })\n  )\n  .build(function (err) {\n    if (err) throw err\n    console.log('Build finished!')\n  })\n```\n\n## Installation\n\nNPM:\n\n```\nnpm install metalsmith\n```\n\nYarn:\n\n```\nyarn add metalsmith\n```\n\n## Quickstart\n\nWhat if you want to get fancier by hiding unfinished drafts, grouping posts in collections, and using custom permalinks? Just add plugins...\n\n```js\nimport { fileURLToPath } from 'node:url'\nimport { dirname } from 'node:path'\nimport Metalsmith from 'metalsmith'\nimport collections from '@metalsmith\u002Fcollections'\nimport layouts from '@metalsmith\u002Flayouts'\nimport markdown from '@metalsmith\u002Fmarkdown'\nimport permalinks from '@metalsmith\u002Fpermalinks'\nimport drafts from '@metalsmith\u002Fdrafts'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\nconst t1 = performance.now()\nconst devMode = process.env.NODE_ENV === 'development'\n\nMetalsmith(__dirname) \u002F\u002F parent directory of this file\n  .source('.\u002Fsrc') \u002F\u002F source directory\n  .destination('.\u002Fbuild') \u002F\u002F destination directory\n  .clean(true) \u002F\u002F clean destination before\n  .env({\n    \u002F\u002F pass NODE_ENV & other environment variables\n    DEBUG: process.env.DEBUG,\n    NODE_ENV: process.env.NODE_ENV\n  })\n  .metadata({\n    \u002F\u002F add any variable you want & use them in layout-files\n    sitename: 'My Static Site & Blog',\n    siteurl: 'https:\u002F\u002Fexample.com\u002F',\n    description: \"It's about saying »Hello« to the world.\",\n    generatorname: 'Metalsmith',\n    generatorurl: 'https:\u002F\u002Fmetalsmith.io\u002F'\n  })\n  .use(drafts(devMode)) \u002F\u002F only include drafts when NODE_ENV === 'development'\n  .use(\n    collections({\n      \u002F\u002F group all blog posts by adding key\n      posts: 'posts\u002F*.md' \u002F\u002F collections:'posts' to metalsmith.metadata()\n    })\n  ) \u002F\u002F use `collections.posts` in layouts\n  .use(\n    markdown({\n      \u002F\u002F transpile all md file contents into html\n      keys: ['description'], \u002F\u002F and also file.description\n      globalRefs: {\n        \u002F\u002F define links available to all markdown files\n        home: 'https:\u002F\u002Fexample.com'\n      }\n    })\n  )\n  .use(permalinks()) \u002F\u002F change URLs to permalink URLs\n  .use(\n    layouts({\n      \u002F\u002F wrap layouts around html\n      pattern: '**\u002F*.html'\n    })\n  )\n  .build((err) => {\n    \u002F\u002F build process\n    if (err) throw err \u002F\u002F error handling is required\n    console.log(`Build success in ${((performance.now() - t1) \u002F 1000).toFixed(1)}s`)\n  })\n```\n\nRead the docs in full at \u003Chttps:\u002F\u002Fmetalsmith.io>\n\n## How does it work?\n\nMetalsmith works in three simple steps:\n\n1. Read all the files in a source directory.\n2. Invoke a series of plugins that manipulate the files.\n3. Write the results to a destination directory!\n\nEach plugin is invoked with the contents of the source directory, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...\n\n```yml\n---\ntitle: A Catchy Title\ndate: 2024-01-01\n---\nAn informative article.\n```\n\n...would be parsed into...\n\n```js\n{\n  'path\u002Fto\u002Fmy-file.md': {\n    title: 'A Catchy Title',\n    date: new Date(2024, 1, 1),\n    contents: Buffer.from('An informative article'),\n    stats: fs.Stats\n  }\n}\n```\n\n...which any of the plugins can then manipulate however they want. Writing plugins is incredibly simple, just take a look at the [example drafts plugin](examples\u002Fdrafts-plugin\u002Findex.js).\n\nOf course they can get a lot more complicated too. That's what makes Metalsmith powerful; the plugins can do anything you want!\n\n## Plugins\n\nA [Metalsmith plugin](https:\u002F\u002Fmetalsmith.io\u002Fapi\u002F#Plugin) is a function that is passed the file list, the metalsmith instance, and a done callback.\nIt is often wrapped in a plugin initializer that accepts configuration options.\n\nCheck out the official plugin registry at: https:\u002F\u002Fmetalsmith.io\u002Fplugins.  \nFind all the core plugins at: https:\u002F\u002Fgithub.com\u002Fsearch?q=org%3Ametalsmith+metalsmith-plugin  \nSee [the draft plugin](examples\u002Fdrafts-plugin) for a simple plugin example.\n\n## API\n\nCheck out the full API reference at: https:\u002F\u002Fmetalsmith.io\u002Fapi.\n\n## CLI\n\nIn addition to a simple [Javascript API](#api), the Metalsmith CLI can read configuration from a `metalsmith.json` file, so that you can build static-site generators similar to [Jekyll](https:\u002F\u002Fjekyllrb.com) or [Hexo](https:\u002F\u002Fhexo.io) easily. The example blog above would be configured like this:\n\n`metalsmith.json`\n\n```json\n{\n  \"source\": \"src\",\n  \"destination\": \"build\",\n  \"clean\": true,\n  \"metadata\": {\n    \"sitename\": \"My Static Site & Blog\",\n    \"siteurl\": \"https:\u002F\u002Fexample.com\u002F\",\n    \"description\": \"It's about saying »Hello« to the world.\",\n    \"generatorname\": \"Metalsmith\",\n    \"generatorurl\": \"https:\u002F\u002Fmetalsmith.io\u002F\"\n  },\n  \"plugins\": [\n    { \"@metalsmith\u002Fdrafts\": true },\n    { \"@metalsmith\u002Fcollections\": { \"posts\": \"posts\u002F*.md\" } },\n    { \"@metalsmith\u002Fmarkdown\": true },\n    { \"@metalsmith\u002Fpermalinks\": \"posts\u002F:title\" },\n    { \"@metalsmith\u002Flayouts\": true }\n  ]\n}\n```\n\nThen run:\n\n```bash\nmetalsmith\n\n# Metalsmith · reading configuration from: \u002Fpath\u002Fto\u002Fmetalsmith.json\n# Metalsmith · successfully built to: \u002Fpath\u002Fto\u002Fbuild\n```\n\nOptions recognised by `metalsmith.json` are `source`, `destination`, `concurrency`, `metadata`, `clean` and `frontmatter`.\nCheckout the [static site](examples\u002Fstatic-site), [Jekyll](examples\u002Fjekyll) examples to see the CLI in action.\n\n### Local plugins\n\nIf you want to use a custom plugin, but feel like it's too domain-specific to be published to the world, you can include plugins as local npm modules: (simply use a relative path from your root directory)\n\n```json\n{\n  \"plugins\": [{ \".\u002Flib\u002Fmetalsmith\u002Fplugin.js\": true }]\n}\n```\n\n## The secret...\n\nWe often refer to Metalsmith as a \"static site generator\", but it's a lot more than that. Since everything is a plugin, the core library is just an abstraction for manipulating a directory of files.\n\nWhich means you could just as easily use it to make...\n\n- [A project scaffolder.](examples\u002Fproject-scaffolder)\n- [A build tool for Sass files.](examples\u002Fbuild-tool)\n- [A simple static site generator.](examples\u002Fstatic-site)\n- [A Jekyll-like static site generator.](examples\u002Fjekyll)\n\n## Resources\n\n- [Gitter Matrix community chat](https:\u002F\u002Fapp.gitter.im\u002F#\u002Froom\u002F#metalsmith_community:gitter.im) for chat, questions\n- [X (formerly Twitter) announcements](https:\u002F\u002Fx.com\u002F@metalsmithio) and the [metalsmith.io news page](https:\u002F\u002Fmetalsmith.io\u002Fnews) for updates\n- [emmer.dev on metalsmith](https:\u002F\u002Femmer.dev\u002Fblog\u002Ftag\u002Fmetalsmith\u002F) - A good collection of various how to's for metalsmith\n- [glinka.co on metalsmith](https:\u002F\u002Fwww.glinka.co\u002Fblog\u002F) - Another great collection of advanced approaches for developing metalsmith\n- [Getting to Know Metalsmith](https:\u002F\u002Frobinthrift.com\u002Fposts\u002Fgetting-to-know-metalsmith\u002F) - a great series about how to use Metalsmith for your static site.\n\n## Troubleshooting\n\nSet `metalsmith.env('DEBUG', '*metalsmith*')` to debug your build. This will log debug logs for all plugins using the built-in `metalsmith.debug` debugger.\nFor older plugins using [debug](https:\u002F\u002Fgithub.com\u002Fdebug-js\u002Fdebug\u002F) directly, run your build with `export DEBUG=metalsmith-*,@metalsmith\u002F*` (Linux) or `set DEBUG=metalsmith-*,@metalsmith\u002F*` for Windows.\n\n### Node Version Requirements\n\nFuture Metalsmith releases will at least support the oldest supported Node LTS versions.\n\nMetalsmith 2.7.x supports NodeJS versions 16.0.0 and higher.\nMetalsmith 2.6.x supports NodeJS versions 14.18.0 and higher.  \nMetalsmith 2.5.x supports NodeJS versions 12 and higher.  \nMetalsmith 2.4.x supports NodeJS versions 8 and higher.  \nMetalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.\n\n### Compatibility & support policy\n\nMetalsmith is supported on all common operating systems (Windows, Linux, Mac).\nMetalsmith releases adhere to [semver (semantic versioning)](https:\u002F\u002Fsemver.org\u002F) with 2 minor gray-area exceptions for what could be considered breaking changes:\n\n- Major Node version support for EOL (End of Life) versions can be dropped in minor releases\n- If a change represents a major improvement that is backwards-compatible with 99% of use cases (not considering outdated plugins), they will be considered eligible for inclusion in minor version updates.\n\n## Credits\n\nSpecial thanks to [Ian Storm Taylor](https:\u002F\u002Fgithub.com\u002Fianstormtaylor), [Andrew Meyer](https:\u002F\u002Fgithub.com\u002FAjedi32), [Dominic Barnes](https:\u002F\u002Fgithub.com\u002Fdominicbarnes), [Andrew Goodricke](https:\u002F\u002Fgithub.com\u002Fwoodyrew), [Ismay Wolff](https:\u002F\u002Fgithub.com\u002Fismay), [Kevin Van Lierde](https:\u002F\u002Fgithub.com\u002Fwebketje) and [others](https:\u002F\u002Fgithub.com\u002Fmetalsmith\u002Fmetalsmith\u002Fgraphs\u002Fcontributors) for their contributions!\n\n## [License](LICENSE)\n\n[npm-badge]: https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fmetalsmith.svg\n[npm-url]: https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fmetalsmith\n[ci-badge]: https:\u002F\u002Fgithub.com\u002Fmetalsmith\u002Fmetalsmith\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg\n[ci-url]: https:\u002F\u002Fgithub.com\u002Fmetalsmith\u002Fmetalsmith\u002Factions\u002Fworkflows\u002Ftest.yml\n[codecov-badge]: https:\u002F\u002Fcoveralls.io\u002Frepos\u002Fgithub\u002Fmetalsmith\u002Fmetalsmith\u002Fbadge.svg?branch=master\n[codecov-url]: https:\u002F\u002Fcoveralls.io\u002Fgithub\u002Fmetalsmith\u002Fmetalsmith?branch=master\n[license-badge]: https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fmetalsmith\u002Fmetalsmith\n[license-url]: LICENSE\n\n[gitter-badge]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F[gitter:matrix]-join-blue.svg\n[gitter-url]: https:\u002F\u002Fapp.gitter.im\u002F#\u002Froom\u002F#metalsmith_community:gitter.im\n","Metalsmith 是一个基于 Node.js 的极简静态网站生成器。其核心功能是通过插件机制来处理所有逻辑，用户只需将所需的插件串联起来即可完成网站构建。支持 Markdown 转换为 HTML、模板布局、自定义永久链接等特性，且易于扩展更多功能如草稿隐藏、文章分类等。适用于需要快速搭建博客或小型静态网站的场景，特别是对于偏好使用 JavaScript 生态工具链的开发者来说，是一个轻量级而灵活的选择。","2026-06-11 03:27:06","top_topic"]