metalsmith-sass

metalsmith-sass

A Sass plugin for Metalsmith.

Installation

npm install --save metalsmith-sass node-sass

Note: As of v2.0, node-sass is listed as a peer dependency, and will need to be installed alongside metalsmith-sass as shown above.

Getting Started

If you haven't checked out Metalsmith before, head over to their website and check out the documentation.

CLI Usage

If you are using the command-line version of Metalsmith, you can install via npm, and then add the metalsmith-sass key to your metalsmith.json file:

{
  "plugins": {
    "metalsmith-sass": {
      "outputStyle": "expanded"
    }
  }
}

JavaScript API

If you are using the JS Api for Metalsmith, then you can require the module and add it to your .use() directives:

var sass = require("metalsmith-sass");

metalsmith.use(sass({
  outputStyle: "expanded"
}));

Options

See node-sass for a complete list of supported options.

In addition to the options that node-sass provides, metalsmith-sass provides the following options:

outputDir

Change the base folder path styles are output to. You can use this in combination with Metalsmith's destination option to control where styles end up after the build.

The final output directory is equal to Metalsmith.destination() + outputDirOption. For example, the following setup output styles to build/css/ even though the source files are in src/scss/:

Metalsmith()
  .source("src/")
  .destination("build/")
  .use(sass({
    outputDir: "css/"   // This changes the output dir to "build/css/" instead of "build/scss/"
  }))
  .build(function () {
    done();
  });

As of version v1.1, you can also use a function to dynamically manipulate the output dir.

This is useful if you want to preserve your folder structure, but change just one folder name.

Metalsmith(__dirname)
  .source("src/")
  .destination("build/")
  .use(sass({
    outputDir: function(originalPath) {
      // this will change scss/some/path to css/some/path
      return originalPath.replace("scss", "css");
    }
  }))
  .build(function () {
    done();
  });

Source Maps

The easiest way to enable source maps in your metalsmith project is to add the following options:

Metalsmith(__dirname)
  .source("src/")
  .destination("build/")
  .use(sass({
    sourceMap: true,
    sourceMapContents: true   // This will embed all the Sass contents in your source maps.
  }))
  .build(function () {
    done();
  });

Though the sourceMapContents is not required, I recommend adding it, otherwise you'll need to manually serve up your .scss files along with your compiled .css files when you publish your site.

.sass files

As of version v1.2, metalsmith-sass automatically handles .sass files, so you don't need to specify the indentedSyntax option. Though you might still need set options for indentType and indentWidth if you are using something other than 2 spaces for indentation.

Credits

Thanks to Segment.io for creating and open-sourcing Metalsmith! Also thanks to the whole community behind the node-sass project.

Changelog

v2.0.0

01/06/2022

BREAKING CHANGE: node-sass has been changed from a direct dependency to a peer dependency. If you are upgrading from v1.x.x, you may need to install it directly in your project using npm install --save node-sass.

• Changed node-sass to a peer dependency. This gives you direct control over which version of node-sass you want to use in your project going forward. No more waiting for metalsmith-sass releases!
• Upgraded dependencies and resolved vulnerabilities.
• Remove test files from npm distribution.
• Enable support for all versions of Node.js supported by node-sass. Going forward, whichever version of node-sass you install will determine your Node.js support. See node-sass' version support policy for details.