{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.

This standardized approach delivers several key benefits to both developers and users. Developers will appreciate the reduced development time, as there's no need to recreate configuration files and project structure for each new plugin. Users benefit from a consistent experience across plugins that follow the same patterns, making it easier to adopt new tools as they're released. The entire community gains from improved maintainability through standard testing and documentation practices. The template also embraces modern practices with dual ESM/CommonJS support, GitHub Actions workflows, and comprehensive testing approaches baked in from the start.

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 is comprehensive, covering both ESM and CommonJS imports to ensure your plugin works in all environments.

For code quality and consistency, the template includes modern tooling with 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.

Contributing to the Metalsmith Ecosystem

By using this template, you're contributing to a more consistent and maintainable Metalsmith ecosystem. The community benefits from a lower barrier to entry for new plugin developers, while also gaining improved code quality through standardized testing and linting practices. Users enjoy a better experience with consistent documentation and interfaces across plugins, and everyone benefits from the future-proof architecture that supports modern JavaScript environments.

Getting Started

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

Whether you're building your first plugin or your tenth, this template makes the development process smoother and more enjoyable. I welcome your contributions and feedback to make this template even better.

Happy building!

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