Skip to content
A Metalsmith plugin that renames files matching a given pattern.
JavaScript HTML
Branch: master
Clone or download



This is a plugin for Metalsmith that renames files matching a given pattern. Presently it only accepts files, not folders, but folder renaming is planned for the near future.

❄️ Project Status

This project is on somewhat of an auto-pilot which means:

  • As I don't use Metalsmith any more, I'm not familiar enough with it to provide support with issues.
  • I will accept fixes and feature PRs only if:

Thanks for your understanding!


If using the CLI for Metalsmith, metalsmith-renamer can be used like any other plugin by including it in metalsmith.json. For example:

For Metalscript's JavaScript API, metalsmith-renamer can be used like any other plugin, by attaching it to the function invocation chain on the Metalscript object. For example:

var renamer = require('metalsmith-renamer');
    filesToRename: { // this name is only used to help organize different settings
      pattern: 'folder/**/*.md',
      rename: function(name) {
        return 'renamed' + name;
    moreFiles: {
      pattern: 'folder/about.html',
      rename: 'index.html'
    }, // and as many more patterns as you want


metalsmith-renamer has two options, both of which must be defined:

  • pattern: option which uses minimatch to find files to rename.
  • rename: which takes a string argument for what you'd like the files to be named, or a function that takes a matched file name and returns the new one to be used.

Use cases

  • I use it to simulate metalsmith-permalinks partially by renaming certain files index.html, allowing me to link straight to directories and not have to use the filename. metalsmith-permalink insists on enclosing files within a structured folder system, whereas I have folder already organized manually.
You can’t perform that action at this time.