Compiles Sass CSS files to CSS stylesheets.

The content of the input document is compiled to CSS and the content of the output document contains the compiled CSS stylesheet.

Package

This module exists in the Wyam.Sass package which is not part of the core distribution. Add the following preprocessor directive to your configuration file to use it:

#n Wyam.Sass

Examples

This is a pipeline that compiles two Sass CSS files, one for Bootstrap (which contains a lot of includes) and a second for custom CSS.

Pipelines.Add("Sass",
    ReadFiles("master.scss"),
    Concat(ReadFiles("foundation.scss")),
    Sass().WithCompactOutputStyle(),
    WriteFiles(".css")
);

Another common pattern is building Bootstrap from npm sitting alongside your "input" folder in a "node_modules" folder. This can be accomplished with a pipeline that looks similar to the following. It loads the Bootstrap Sass files that don't begin with "_" from the Bootstrap node module and then outputs the results to a specific path under your output folder (in this case, "assets/css/bootstrap.css").

Pipelines.Add("Bootstrap",
    ReadFiles("../node_modules/bootstrap/scss/**/{!_,}*.scss"),
    Sass()
        .WithCompactOutputStyle(),
    WriteFiles((doc, ctx) => $"assets/css/{doc.String(Keys.RelativeFilePath)}")
        .UseWriteMetadata(false)
);

Usage

Sass()

Fluent Methods

Chain these methods together after the constructor to modify behavior.

GenerateSourceMap(bool generateSourceMap = true)

Specifies whether a source map should be generated (the default behavior is false).
- generateSourceMap
  true to generate a source map.
IncludeSourceComments(bool includeSourceComments = true)

Sets whether the source comments are included (by default they are not).
- includeSourceComments
  true to include source comments.
WithCompactOutputStyle()

Sets the output style to compact.
WithCompressedOutputStyle()

Sets the output style to compressed.
WithExpandedOutputStyle()

Sets the output style to expanded.
WithImportPath(Func<string, string> importPathFunc)

A delegate that processes the path in @import statements.
- importPathFunc
  A delegate that should return the correct import path for a given import.
WithIncludePaths(params DirectoryPath[] paths)

Adds a list of paths to search while processing includes.
- paths
  The paths to include.
WithInputPath(DocumentConfig inputPath)

Specifies a delegate that should be used to get the input path for each input document. This allows the Sass processor to search the right file system and paths for include files. By default, the Wyam.Common.Meta.Keys.RelativeFilePath metadata value is used for the input document path.
- inputPath
  A delegate that should return a Wyam.Common.IO.FilePath.
WithNestedOutputStyle()

Sets the output style to nested.

Input Metadata

The metadata values listed below apply to individual documents and are typically set from front matter (with just the name of the key) and used as inputs to the module to control behavior.

Keys.RelativeFilePath: Wyam.Common.IO.FilePath

If Wyam.Common.Meta.Keys.SourceFilePath is unavailable, this is used to guess at the source file path.
Keys.SourceFilePath: Wyam.Common.IO.FilePath

The default key to use for determining the input document path.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.