Skip to content

Commit

Permalink
Annotate sbt examples to enable highlighting
Browse files Browse the repository at this point in the history
  • Loading branch information
jonas committed Sep 2, 2016
1 parent 9cd59b2 commit 878168a
Showing 1 changed file with 31 additions and 31 deletions.
62 changes: 31 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,34 +46,34 @@ 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)
```

Note that the plugin will generate an error if a variable is found in the source file with no matching value in `preprocessVars`.

The setting `preprocessIncludeFilter` is used to define the filename extensions that should be processed when `makeSite` is run.

```
```sbt
preprocessIncludeFilter := "*.md" | "*.markdown"
```

Expand All @@ -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"
Expand All @@ -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"
```
Expand All @@ -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"
```
Expand All @@ -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"
```
Expand All @@ -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"
```
Expand All @@ -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")
```

Expand All @@ -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"
```
Expand All @@ -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
```

Expand All @@ -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
```

Expand All @@ -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")

Expand Down

0 comments on commit 878168a

Please sign in to comment.