{Werner Glinka}

Introducing my Metalsmith Plugin Template

While working on my blog series Metalsmith Redux - Static Site Generation in 2025, I developed several new plugins with the assistance of Claude AI. I found myself repeatedly modifying the Metalsmith core plugin structure for each new project, which led me to create a standardized template. This starter template simplified my plugin development and ensured consistency across my plugins.

What's Included in the Template?

The template provides a complete foundation for a modern Metalsmith plugin. You'll find dual module support for both ESM and CommonJS to ensure maximum compatibility across different Node.js environments. The template comes with pre-configured GitHub Actions workflows for automated testing and coverage reporting, saving you the trouble of setting up CI/CD pipelines from scratch. The testing setup covers both ESM and CommonJS imports to ensure your plugin works in all environments and gives you a good starting point for your own tests.

For code quality and consistency, the template includes ESLint 9.x and Prettier configurations. Release management is simplified through integration with release-it and conventional changelog generation. Developer experience is enhanced with JSDoc typing that provides excellent IDE support without requiring TypeScript. All of this is wrapped in a standard documentation structure that ensures a consistent experience for users of your plugin.

How to Use the Template

Getting started with a new Metalsmith plugin is now easier than ever:

1. Clone the Template

git clone https://github.com/wernerglinka/metalsmith-plugin-template.git metalsmith-your-plugin-name
cd metalsmith-your-plugin-name
rm -rf .git
git init

2. Update Plugin Information

Search and replace the following placeholders throughout the project:

  • metalsmith-plugin-name → Your plugin name (e.g., metalsmith-markdown-extra)
  • plugin-name → The short version (e.g., markdown-extra)
  • pluginName → The camelCase version (e.g., markdownExtra)
  • A Metalsmith plugin to ... → Your plugin description

The main files to update are:

  • package.json (name, description, repository URLs)
  • README.md (badges, description, examples)
  • src/index.js (plugin function name and JSDoc comments)

3. Install Dependencies

npm install

4. Implement Your Plugin

The template provides a fully tested plugin structure in src/index.js. Modify it to implement your specific functionality while maintaining the two-phase plugin pattern:

function yourPluginName(options = {}) {
  // Normalize options with defaults
  const opts = {
    defaultOption: true,
    ...options
  };
  
  return function yourPluginName(files, metalsmith, done) {
    const debug = metalsmith.debug ? metalsmith.debug('metalsmith-your-plugin-name') : () => {};
    debug('Processing with options: %O', opts);
    
    // Process files...
    
    done();
  };
}

5. Write Tests

Update the pre-configured tests in:

  • test/index.js - Main ESM tests
  • test/cjs.test.cjs - CommonJS compatibility tests
  • test/unit/ - Unit tests for specific functionality

The template includes a complete test fixture structure in test/fixtures/ to get you started quickly.

6. Update Documentation

Ensure the README.md contains:

  • Clear description of what your plugin does
  • Installation instructions
  • Usage examples with code samples
  • Options documentation (in table format)
  • Debug instructions
  • Troubleshooting section

7. Test and Build

Run a build before you test as we need to build the ESM and CommonJS versions of your plugin before testing.

npm run build # Build ESM and CommonJS versions
npm test      # Run tests

AI-Assisted Plugin Development

A unique feature of this template is the included PROMPT-TEMPLATE.md file, specifically designed for AI-assisted plugin development. When working with AI assistants like Claude, you can share this template to get structured, consistent help with your plugin development.

The prompt template guides AI systems with clear instructions on plugin requirements and architecture, code standards and implementation patterns, testing approaches, and documentation needs. It also helps AI assistants avoid common pitfalls in Metalsmith plugin development. This approach has helped me develop several robust plugins in a fraction of the time it would typically take, and I believe it can do the same for you.

Getting Started

The Metalsmith Plugin Template is available now on GitHub at wernerglinka/metalsmith-plugin-template.

I hope that this template makes your development process smoother and more enjoyable.

I'd love to hear your feedback on this template and how it could be improved. Let me know on Bluesky or open an issue on GitHub.

Scroll to top