sbt / website

The source for scala-sbt.org

scala-sbt.org

This project is the source for scala-sbt.org. It generates the contents of the site in sbt/sbt.github.com for delivery via GitHub Pages.

See contributors for the list of documentation contributors.

scala-sbt.org is powered by:

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

• Pandoc 2.3.1, 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 us a pull request if your plugin is not already on it.

Setup

Full setup

The PDF generation is optional, and requires the following additional steps to install TeX Live and Pandoc.

On Ubuntu

$ sudo apt-get install pandoc latex-cjk-all texlive-full

On Mac

These steps are derived from Haruhiko Okumura's instructions at [TeX Live/Mac](https://texwiki.texjp.org/?TeX%20Live%2FMac#bcb0d462 (in Japanese).

• install MacTEX, either via downloaded pkg or homebrew mactex formulae
• update TeX Live package manager with sudo tlmgr update --self --all (this may take a while)
• brew install pandoc

Docusaurus

This website is built using Docusaurus, a modern static website generator.

Local Development

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

$ yarn run build

This command generates static content into the build directory and can be served using any static contents hosting service.

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: sbt/sbt-ghpages#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
• 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 }

License

sbt Copyright 2023 - current, Scala Center at EPFL Copyright 2011 - 2023, Lightbend, Inc. Copyright 2008 - 2010, Mark Harrah Licensed under Apache v2 license (see LICENSE)