The source for scala-sbt.org
HTML Scala CSS Python JavaScript Ruby Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.travis Revert 1.x-beta change Jan 8, 2018
project sbt 1.2.1 Aug 7, 2018
script added syntax hilighting May 25, 2014
src Add sbt-i18n plugin Aug 18, 2018
.gitignore Add sbt dirs to .gitignore Feb 3, 2018
.java-version update notes Aug 11, 2017
.scalafmt.conf introduce scalafmt Aug 14, 2017
.travis.yml Ruby 2.4.4 for Nanoc Aug 7, 2018
README.md Fixes dollar sign Mar 7, 2018
_config.yml rdiscount Oct 24, 2011
build.sbt sbt 1.2.0 Jul 31, 2018

README.md

scala-sbt.org

This project is the source for scala-sbt.org. See contributors for the list of documentation contributors.

scala-sbt.org is powered by:

  • nanoc to generate the landing pages.

  • Pamflet, a Scala-based documentation engine written by @n8han (and some contributions from @eed3si9n) generates the sbt 0.13/1.x documentation.

  • Pandoc, to generate pdf files.

The site generation is driven by sbt-site and sbt-ghpages.

Attention plugin authors

The source for Community plugins page is at src/reference/01-General-Info/02-Community-Plugins.md. Add your plugin to this page and send send us a pull request if your plugin is not already on it.

Setup

Minimum setup

Currently, nanoc requires Ruby 2.1 or greater.

You'll need the following gems for running nanoc:

$ gem install nanoc:4.0.2
$ gem install redcarpet
$ gem install nokogiri

If you're running ubuntu, you'll need to also install ruby-dev for the native-code in redcarpet:

$ sudo apt-get install ruby-dev

Full setup

The pdf generation is optional, and requires the following additional steps.

On Ubuntu

$ sudo add-apt-repository ppa:texlive-backports/ppa
$ sudo apt-get update
$ sudo apt-get install pandoc latex-cjk-all texlive-full

On Mac

Usage

To make the site locally, from sbt shell:

> makeSite

Then open target/site/index.html.

To push site, from sbt shell:

> ghpagesPushSite

Beware that sbt-ghpages interacts badly if your home directory is a git repository: https://github.com/sbt/sbt-ghpages/issues/25

Releasing new sbt

  • Make sure you enable pdf generation: sbt -Dsbt.website.generate_pdf
  • Update sbt.version in project/build.properties
  • Update targetSbtFullVersion in project/Docs.scala
  • Add last release to "Previous releases" in src/nanoc/nanoc.yaml
  • Update sbtVersion, windowsBuild and sbtVersionForScalaDoc in src/reference/template.properties

Dollar sign

Pamflet uses dollar sign ($) as the template variable character. So if you use it in the document, use need to escape it with backslash: \$.

Here's how to check for unescaped dollar signs.

$ brew install ripgrep
$ rg '^([^\$]*)[^\\]\$([^\$]*)$' -g '*.md' src

src/reference/02-DetailTopics/03-Dependency-Management/04-Proxy-Repositories.md
79:  export SBT_CREDENTIALS="$HOME/.ivy2/.credentials"

Including code examples

To include a validated code examples, create a scripted test under src/sbt-test, and in the markdown include as:

// This includes the entire file as Scala code snippet
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) {}

or

// This includes snippet between a line containing #example another line with #example
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) { #example }

or

// This specifies syntax highlight
@@snip [build.sbt]($root$/src/sbt-test/ref/basic/build.sbt) { #example type=text }