Skip to content

sbt-uni-javadoc Plugin ​

sbt-uni-javadoc shrinks the -javadoc.jar your build publishes, so a release stays within Maven Central's publishing limits. It works for any sbt 2.x project, with or without the uni library.

When to use it ​

Maven Central caps how much each organization can publish per month, and Scaladoc output is often the largest part of a Scala release (scala/scala3#26387). Maven Central still requires a -javadoc.jar for every artifact, so the jar cannot simply be dropped. Reach for this plugin when:

  • your organization publishes many artifacts or frequent releases and is close to the limit, or
  • you cross-build for Scala.js or Scala Native, whose Scaladoc repeats the JVM artifact's API, or
  • you publish sbt plugins, whose users read guides rather than Scaladoc.

Uni uses it for its own releases. About 58% of a uni release was -javadoc.jar before.

sbt 2.x only

The plugin targets sbt 2.x (its metabuild runs on Scala 3).

Installation ​

In project/plugins.sbt:

scala
addSbtPlugin("org.wvlet.uni" % "sbt-uni-javadoc" % "2026.2.0")

This also brings in sbt-salad-days, which strips fonts and inkuire.js from Scaladoc output automatically. sbt-salad-days is a great choice on its own if that is all you need; this plugin adds the reductions below on top of it.

Nothing else changes until you add a setting: choosing which artifacts get which javadoc is your build's decision. Each setting below is a Seq[Setting[?]] you add to a project's settings.

Settings ​

minimizeScaladoc: keep the full Scaladoc, smaller ​

scala
lazy val core = project
  .settings(minimizeScaladoc)

By default Scaladoc embeds the whole navigation side menu in every HTML page (about 100 KB per page). minimizeScaladoc adds -dynamic-side-menu, which writes the menu once to dynamicSideMenu.json and renders it with JavaScript.

Scaladoc up to 3.10 builds broken side-menu links when the docs are not served from the root of a host, as on javadoc.io (scala/scala3#27403). The setting patches scripts/ux.js in the jar with that fix, and warns once a Scaladoc version no longer needs the patch.

On Scala 2 the setting does nothing, because Scala 2 Scaladoc has no -dynamic-side-menu option. It is safe to add to settings shared by Scala 2 and Scala 3 builds.

scala
lazy val core = crossProject(JVMPlatform, JSPlatform, NativePlatform)
  .settings(minimizeScaladoc)
  .jsSettings(minimizeJavadoc)
  .nativeSettings(minimizeJavadoc)

For a Scala.js or Scala Native artifact whose JVM artifact is also published, the jar holds only index.html and README.md. They link to the JVM artifact's Scaladoc on javadoc.io (https://javadoc.io/doc/<organization>/<name>_<scala binary version>/<version>) and to javadocSiteUrl. Scaladoc does not run, so the release build gets faster too.

Do not add it to a module that is Scala.js or Native only: its Scaladoc is the only place its API is published.

scala
lazy val plugin = project
  .enablePlugins(SbtPlugin)
  .settings(minimizePluginJavadoc)

For sbt plugins and other artifacts that users learn from guides, the jar holds only index.html and README.md linking to javadocSiteUrl and javadocSourceUrl.

To link to one guide page and one source directory, pass their paths:

scala
lazy val plugin = project
  .enablePlugins(SbtPlugin)
  .settings(
    minimizePluginJavadoc(guide = "build/my-plugin", sourceDir = "my-plugin/src/main/scala")
  )

This links to <javadocSiteUrl>/build/my-plugin and <javadocSourceUrl>/tree/<ref>/my-plugin/src/main/scala, the GitHub URL layout, where <ref> is v<version> for a release and main for a snapshot.

SettingDefaultUsed for
javadocSiteUrlhomepageThe guides (website) link
javadocSourceUrlscmInfo browseUrlThe source code link

Set them when the defaults point elsewhere, for example when homepage is the repository rather than the website:

scala
ThisBuild / javadocSiteUrl := "https://example.org/my-library/"

A link whose setting and default are both unset is left out of the page.

Released under the Apache 2.0 License.