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.
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.
The Book of sbt is written using mdBook a command line tool to create books with Markdown.
The landing page is built using Docusaurus, a modern static website generator.
$ 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.
$ yarn run build
This command generates static content into the build
directory and can be served using any static contents hosting service.
The PDF generation is optional, and requires the following additional steps to install TeX Live and Pandoc.
$ sudo apt-get install pandoc latex-cjk-all texlive-full
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
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
- Make sure you enable pdf generation:
sbt -Dsbt.website.generate_pdf
- Update
sbt.version
inproject/build.properties
- Update
targetSbtFullVersion
inproject/Docs.scala
- Update
sbtVersion
,windowsBuild
andsbtVersionForScalaDoc
insrc/reference/template.properties
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"
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 }
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)