From 878168a24016c3e7779abcc7043df38dbeb6765f Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Thu, 1 Sep 2016 20:38:19 -0400 Subject: [PATCH] Annotate sbt examples to enable highlighting --- README.md | 62 +++++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index d292973..b899c8a 100644 --- a/README.md +++ b/README.md @@ -46,26 +46,26 @@ When you run `makeSite`, your project's webpage is generated in the `target/site The `src/site` directory can be overridden via the `siteSourceDirectory` key: -``` +```sbt siteSourceDirectory <<= target / "generated-stuff" ``` Additional files outside of `siteSourceDirectory` can be added individually via the `siteMappings` key: -``` +```sbt siteMappings ++= Seq(file1 -> "location.html", file2 -> "image.png") ``` ### Static Content with Variable Substitution The site plugin supports basic variable substitution when copying files from `src/site-preprocess`. To enable, add this to your `build.sbt` file: -``` +```sbt enablePlugins(PreprocessPlugin) ``` Variables are delimited by surrounding the name with `@` symbols (e.g. `@VERSION@`). Values are assigned to variables via the setting `preprocessVars: [Map[String, String]]`. For example: -``` +```sbt preprocessVars := Map("VERSION" -> version.value, "DATE" -> new Date().toString) ``` @@ -73,7 +73,7 @@ Note that the plugin will generate an error if a variable is found in the source The setting `preprocessIncludeFilter` is used to define the filename extensions that should be processed when `makeSite` is run. -``` +```sbt preprocessIncludeFilter := "*.md" | "*.markdown" ``` @@ -82,26 +82,26 @@ The default filter is `"*.txt" | "*.html" | "*.md" | "*.rst"`. ### Jekyll Site Generation The `sbt-site` plugin has direct support for running [Jekyll]. This is useful for supporting custom Jekyll plugins that are not allowed when publishing to GitHub, or hosting a Jekyll site on your own server. To add Jekyll support, enable the associated plugin: -``` +```sbt enablePlugins(JekyllPlugin) ``` This assumes you have a Jekyll project in the `src/jekyll` directory. To change this, set the key `sourceDirectory` in the `Jekyll` scope: -``` +```sbt sourceDirectory in Jekyll := sourceDirectory.value / "hyde" ``` To redirect the output to a subdirectory of `target/site`, use the `siteSubdirName` key in `Jekyll` scope: -``` +```sbt // Puts output in `target/site/notJekyllButHyde` siteSubdirName in Jekyll := "notJekyllButHyde" ``` 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: -``` +```sbt requiredGems := Map( "jekyll" -> "0.11.2", "liquid" -> "2.3.0" @@ -111,19 +111,19 @@ requiredGems := Map( ### Sphinx Site Generation The `sbt-site` plugin has direct support for building [Sphinx] projects. To enable Sphinx site generation, simply enable the associated plugin in your `build.sbt` file: -``` +```sbt enablePlugins(SphinxPlugin) ``` This assumes you have a Sphinx project under the `src/sphinx` directory. To change this, set the `sourceDirectory` key in the `Sphinx` scope: -``` +```sbt sourceDirectory in Sphinx := sourceDirectory.value / "androsphinx" ``` Similarly, the output can be redirected to a subdirectory of `target/site` via the `siteSubdirName` key in `Sphinx` scope: -``` +```sbt // Puts output in `target/site/giza` siteSubdirName in Sphinx := "giza" ``` @@ -132,19 +132,19 @@ siteSubdirName in Sphinx := "giza" The `sbt-site` plugin has direct support for building [Pamflet] projects. To enable Pamflet site generation, simply enable the associated plugin in your `build.sbt` file: -``` +```sbt enablePlugins(PamfletPlugin) ``` This assumes you have a Pamflet project under the `src/pamflet` directory. To change this, set the `sourceDirectory` key in the `Pamflet` scope: -``` +```sbt sourceDirectory in Pamflet := sourceDirectory.value / "papyrus" ``` Similarly, the output can be redirected to a subdirectory of `target/site` via the `siteSubdirName` key in `Pamflet` scope: -``` +```sbt // Puts output in `target/site/parchment` siteSubdirName in Pamflet := "parchment" ``` @@ -153,19 +153,19 @@ siteSubdirName in Pamflet := "parchment" The `sbt-site` plugin has direct support for building [Nanoc] projects. To enable Nanoc site generation, simply enable the associated plugin in your `build.sbt` file: -``` +```sbt enablePlugins(NanocPlugin) ``` This assumes you have a Nanoc project under the `src/nanoc` directory. To change this, set the `sourceDirectory` key in the `Nanoc` scope: -``` +```sbt sourceDirectory in Nanoc := sourceDirectory.value / "conan" ``` Similarly, the output can be redirected to a subdirectory of `target/site` via the `siteSubdirName` key in `Nanoc` scope: -``` +```sbt // Puts output in `target/site/conan` siteSubdirName in Nanoc := "conan" ``` @@ -174,19 +174,19 @@ siteSubdirName in Nanoc := "conan" ### Asciidoctor Site Generation The `sbt-site` plugin has direct support for building [Asciidoctor] projects. To enable Asciidoctor site generation, simply enable the associated plugin in your `build.sbt` file: -``` +```sbt enablePlugins(AsciidoctorPlugin) ``` This assumes you have an Asciidoctor project under the `src/asciidoctor` directory. To change this, set the `sourceDirectory` key in the `Asciidoctor` scope: -``` +```sbt sourceDirectory in Asciidoctor := sourceDirectory.value / "asciimd" ``` Similarly, the output can be redirected to a subdirectory of `target/site` via the `siteSubdirName` key in `Asciidoctor` scope: -``` +```sbt // Puts output in `target/site/asciimd` siteSubdirName in Asciidoctor := "asciimd" ``` @@ -196,26 +196,26 @@ siteSubdirName in Asciidoctor := "asciimd" The `sbt-site` plugin has direct support for building [GitBook] projects. To enable GitBook site generation, simply enable the associated plugin in your `build.sbt` file: -``` +```sbt enablePlugins(GitBookPlugin) ``` This assumes you have a GitBook project under the `src/gitbook` directory. To change this, set the `sourceDirectory` key in the `GitBook` scope: -``` +```sbt sourceDirectory in GitBook := sourceDirectory.value / "doc" ``` Similarly, the output can be redirected to a subdirectory of `target/site` via the `siteSubdirName` key in `GitBook` scope: -``` +```sbt // Puts output in `target/site/book` siteSubdirName in GitBook := "book" ``` The plugin can also be configured to manage all GitBook setup and installation by configuring a dedicated directory in which GitBook's npm packages can be installed. -```scala +```sbt gitbookInstallDir in GitBook := Some(baseDirectory.value / "node_modules" / "gitbook") ``` @@ -236,13 +236,13 @@ sourceDirectory in Paradox := sourceDirectory.value / "doc" ## ScalaDoc APIs To include ScalaDoc with your site, add the following line to your `build.sbt`: -``` +```sbt enablePlugins(SiteScaladocPlugin) ``` This will default to putting the ScalaDoc under the `latest/api` directory on the website. You can change this with the `siteSubdirName` key in the `SiteScaladoc` scope: -``` +```sbt // Puts ScalaDoc output in `target/site/api/wip` siteSubdirName in SiteScaladoc := "api/wip" ``` @@ -254,13 +254,13 @@ See the [sbt-ghpages] plugin for information about publishing to [GitHub Pages]. ## Previewing the Site To preview your generated site, run `previewSite`, which launches a web server on port 4000 and attempts to connect your browser to [http://localhost:4000/](http://localhost:4000/). To change the server port, use the key `previewFixedPort`: -``` +```sbt previewFixedPort := Some(9999) ``` To disable browser auto-open, use the key `previewLaunchBrowser`: -``` +```sbt previewLaunchBrowser := false ``` @@ -269,7 +269,7 @@ To create a zip package of the site run `package-site`. To also include this zip file as an artifact when running `publish`, add the following to your `build.sbt`: -``` +```sbt publishSite ``` @@ -279,7 +279,7 @@ See the [sbt-ghpages] plugin documentation for simplified publishing to [GitHub If you need to run a generator on more than one source directory, bypassing the `AutoPlugin` system and defining one or more sbt `Configuration`s is necessary. For example, suppose you have two Pamflet source directories and want them each generated as a subdirectory under `target/site`. A `build.sbt` might look something like this: -``` +```sbt // Define two `Configuration` instances. val Site1 = config("site1")