A SBT plugin that extends sbt-site by prepending YAML front matter to your github-style README files and including them in the generated site. This allows you to use the same documentation in multiple contexts without any manual duplication.

This plugin is aimed at projects that:

• Use SBT and sbt-site to generate their project web site.

• Use GitHub-style README files for documentation.

• Want to use their GitHub-style READMEs as content on their site.

This plugin provides a minimal DSL that is used to describe what README files are to be included in your site as well as the YAML front-matter to associate with each file.

source - documentation - changelog

Getting Started

Prerequisites:

• JVM 1.5+

• Scala 2.10.4+

• SBT 0.13.2+

To use sbt-ghreadme plugin in your project add the following line to your project/plugins.sbt file:

addSbtPlugin("io.zman" % "sbt-ghreadme" % "1.1")

Configuring the Plugin

First off, add the following to the top of your build.sbt file:

import GhReadmeKeys._

Somewhere below that include the plugin settings (I usually put it after the sbt-site configuration).

ghreadme.settings

The last step is to specify what README files the plugin will process and associate YAML front-matter with those files. By default this plugin will not process any README files, you must specify each file to process individually.

Configuring README Mappings

An example of the common use case where the README.md file in the root of your project is used as the index page of your site:

readmeMappings += {
  "." --- Seq(
    "title"   -> "my cool project",
    "layout"  -> "page"
  )
}

In the above example we specify the README.md file project's root directory simply by naming the directory ("."). Since only the source file is specified, the destination file will be named index.md and placed in the root of the generated site.

README files may be mapped to locations in the generated site that are different from their source locations. For example:

readmeMappings += {
  "." -> "project-info" --- Seq(
    "title"   -> "my cool project",
    "layout"  -> "page"
  )
}

In this example the README.md file in the root of the project will be mapped to project-info/index.md in the generated site.

Mapping Arbitrary Files

This plugin can also be used to map arbitrarily-named markdown files from your project to your generated site. For example:

readmeMappings += {
  "docs/main.md" -> "site-docs/index.md" --- Seq(
    "title"   -> "my cool project",
    "layout"  -> "page"
  )
}

This example will map the docs/main.md file in your project to the site-docs/index.md file in your generated site.