Home Code Other Software

Table of Contents


sbt-lwm (Light Weight Markup) is an SBT 0.11.x plugin that converts lightweight markup documents to HTML. It currently supports Textile and Markdown.

sbt-lwm uses the MarkWrap library to convert the markup to HTML, so it supports converting:


Versions of this plugin prior to 0.3 only work with SBT 0.10.x. Versions of this plugin from 0.3 on only work with SBT 0.11.1 and 0.12.x. Versions from 0.4 onward only work with SBT 0.13.x and better.

If you’re using SBT 0.7, there’s an older version (with fewer features and a different variable syntax) here.

Using the Plugin

Getting the Plugin

Within your SBT project, create project/plugins.sbt (if it doesn’t already exist) and add the following:

addSbtPlugin("org.clapper" % "sbt-lwm" % "0.4.0")

Settings and Tasks

The plugin provides the following settings and tasks.

Note: sbt-lwm uses predefined SBT settings, where possible (e.g., sources). Of course, that’s not always possible. To be sure you’re updating the correct setting, always use the form:

settingName in LWM

For instance:

flatten in LWM := false

sources in LWM <++= baseDirectory map { d =>
  (d / "src" * "*.txt").get ++
  (d / "src" * "*.md").get ++
  (d / "src" * "*.textile").get

targetDirectory in LWM <<= baseDirectory(_ / "target")

cssFile in LWM <<= baseDirectory(d => Some(d / "src" / "style.css" ))

You can find the list of settings and tasks below.



The lightweight markup files to be processed. sbt-lwm uses a file’s extension to recognize what kind of lightweight markup the file contains. The supported extensions are:

For instance, suppose you want to process all Markdown files within your “src” tree. You might set sources like this:

sources in LWM <++= baseDirectory map (d => (d / "src" ** "*.md").get)

If you also want to apply the edits to all files ending in “.markdown” (perhaps because you’re not consistent in your extensions), use either:

sources in LWM <++= baseDirectory map (d => (d / "src" ** "*.md").get)

sources in LWM <++= baseDirectory map (d => (d / "src" ** "*.markdown").get)

or, more succinctly:

sources in LWM <++= baseDirectory { dir =>
  (dir / "src" ** "*.md").get ++
  (dir / "src" ** "*.markdown").get

Front Matter

Each source file can optionally start with front matter, metadata about the document. The front matter must be separated from the rest of the document by a single line like this:


Front matter consists of one or more item: value pairs. Currently, the only supported item is title. To set an individual title for a document, specify the title in the front matter, like so:

title: A very cool user's guide

# My User's Guide

If the title element is omitted, or if the front-matter is missing, then the resulting <title> HTML element will be empty.


A cascading style sheet (CSS) file to include, inline, in the <head> section of the HTML document(s). This setting is a Scala Option pointing to a file. By default, no CSS file is included in the generated HTML.


cssFile in LWM <<= baseDirectory(d => Some(d / "src" / "style.css" ))


The directory to which to write the HTML versions of the source files. For example:

targetDirectory in LWM <<= baseDirectory(_ / "target")

See also flatten, below.


If flatten is true, then the processed HTML files will all be placed directly in targetDirectory; if there are name clashes, then some files will be overwritten. If flatten is false, then the partial path to each source file is preserved in the target directory.

An example will help clarify. Consider the following file tree:

Directory tree

Let’s assume you’re processing all the files ending in “.md”, into the target directory.

sources in LWM <++= baseDirectory(d => (d / "src" ** "*.md").get)

targetDirectory in LWM <<= baseDirectory(_ / "target")

If you also set:

flatten in LWM := true

the edit operation will put all the HTML versions of all three files directly in the target directory.

If, instead, you set:

flatten in LWM := false

you’ll end up with the following edited versions:


The encoding of the source file and, hence, the resulting HTML. Defaults to “UTF-8”.


encoding in LWM := "ISO-8859_1"


sbt-lwm provides two new SBT tasks.

Change log

The change log for all releases is here.


Brian M. Clapper, bmc@clapper.org

Copyright and License

This software is copyright © 2011 Brian M. Clapper and is released under a BSD License.


I gladly accept patches from their original authors. Feel free to email patches to me or to fork the GitHub repository and send me a pull request. Along with any patch you send: