Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Test Release

This is a plugin for Metalsmith which renames files matching a given pattern.

❄️ 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:

import Metalsmith from "metalsmith";
import renamer from "metalsmith-renamer";

      "Markdown Files": { // this name is only used to help organize different settings
        pattern: "folder/**/*.md",
        rename: function (name) {
          return "renamed" + name;
      "HTML Pages": {
        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.


A Metalsmith plugin that renames files matching a given pattern.







No packages published