This is an sbt plugin that can generate project websites.
It is designed to work hand-in-hand with publishing plugins like sbt-ghpages.
Add this to your project/plugins.sbt:
addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.8.2")
Note: this requires sbt 0.13 - for sbt 0.12 see the 0.7.2 version of this plugin.
Note: The release candidate withAutopluginconversion is available here.
And then in your build.sbt file:
site.settings
Then, run make-site to generate your project's webpage in the target/site directory.
See the sbt-ghpages plugin for information about publishing to gh-pages. We expect other publishing mechanisms to be supported in the future.
The sbt-site plugin has specific "support" settings for the various supported ways of generating a site. By default, all files under src/site are included in the site. You can add new generated content in one of the following ways:
Simply add to the site mappings. In your build.sbt file:
site.siteMappings <++= Seq(file1 -> "location.html", file2 -> "image.png")
To change the source directory for static site files, use the siteSourceDirectory alias:
siteSourceDirectory <<= target / "generated-stuff"
The site plugin supports basic variable substitution when copying files from src/site-preprocess. To enable, add this to your build.sbt file:
site.preprocessSite()
Variables are delimited with two @ symbols, e.g. @VERSION@. Variables are defined via the preprocessVars[Map[String, String]] setting. For example:
preprocessVars := Map("VERSION" -> version.value, "DATE" -> new Date().toString)
The setting preprocessExt[Set[String]] is used to define the filename extensions that should be processed when make-site is run. The defaults are Set("txt", "html", "md")
Note: The extension specifications must not include the final dot (
.). Only the symbols after the dot.
The site plugin has direct support for running jekyll locally. This is suprisingly useful for suporting custom jekyll plugins that are not allowed when publishing to github, or hosting a jekyll site on your own server. To add jekyll support, add the following to your build.sbt:
site.jekyllSupport()
This assumes you have a jekyll project in the src/jekyll directory.
One common issue with Jekyll is ensuring that everyone uses the same version for generating a website. There is special support for ensuring the version of gems. To do so, add the following to your build.sbt file:
com.typesafe.sbt.site.JekyllSupport.requiredGems := Map(
"jekyll" -> "0.11.2",
"liquid" -> "2.3.0"
)
The site plugin has direct support for building Sphinx projects locally. This assumes you have a sphinx project under the src/sphinx directory. To enable sphinx site generation, simply add the following to your build.sbt file:
site.sphinxSupport()
The site plugin has direct support for building Pamflet projects. This assumes you have a pamflet project under the src/pamflet directory. To enable pamflet site generation, simply add the following to your build.sbt file:
site.pamfletSupport()
To place pamflet HTML under a directory, run:
site.pamfletSupport("manual")
The above will place pamflet generated HTML under the manual/ directory in the generated site.
The site plugin has direct support for building nanoc projects. This assumes you have a nanoc project under the src/nanoc directory. To enable nanoc site generation, simply simply add the following to your build.sbt file:
site.nanocSupport()
The site plugin has direct support for building Asciidoctor projects locally. This assumes you have a asciidoctor project under the src/asciidoctor directory. To enable asciidoctor site generation, simply add the following to your build.sbt file:
site.asciidoctorSupport()
To include Scaladoc with your site, add the following line to your build.sbt:
site.includeScaladoc()
This will default to putting the scaladoc under the latest/api directory on the website. You can configure this by passing a parameter to the includeScaladoc method:
site.includeScaladoc("alternative/directory")
To preview your generated site, run previewSite to open a web server. Direct your web browser to http://localhost:4000/ to view your site.
To create a zip package of the site run package-site.
To also publish this zip file when running publish, add the following to your build.sbt:
site.publishSite
sbt-site is released under a "BSD 3-Clause" license. See LICENSE for specifics and copyright declaration.