Groups

Paradox supports ‘groups’ which allow users to easily switch between different variants of the documentation.

Configuration

Groups must be configured through sbt:

.enablePlugins(NoPublish, ParadoxPlugin)
  .settings(
    name := "paradox docs",
    paradoxTheme := Some(builtinParadoxTheme("generic")),
    paradoxGroups := Map("Language" -> Seq("Scala", "Java"))
  )

Syntax

Tabs

Groups are used for tabs, where the group is determined by the tab name:

Java
:   @@snip [example-first.java](/docs/src/main/resources/tab-switching/examples.java) { #java_first }

Scala
:   @@snip [example-first.scala](/docs/src/main/resources/tab-switching/examples.scala) { #scala_first }

Java

copysourceclass JavaFirst {
  public static void main(String[] args) {
    System.out.println("Hello java!");
  }
}

Scala

copysourceobject ScalaFirst extends App {
  println("Hello scala!")
}

or by the group parameter on the snippet:

example-first.java
:   @@snip [example-first.java](../../resources/tab-switching/examples.java) { #java_first group=java }

example-first.scala
:   @@snip [example-first.scala](/docs/src/main/resources/tab-switching/examples.scala) { #scala_first group=scala }

example-first.java

copysourceclass JavaFirst {
  public static void main(String[] args) {
    System.out.println("Hello java!");
  }
}

example-first.scala

copysourceobject ScalaFirst extends App {
  println("Hello scala!")
}

But tabs not associated with groups are left alone:

sbt

copysourcelibraryDependencies += "com.lightbend.akka" %% "akka-stream-alpakka-cassandra" % "0.3"

Maven

copysource<dependency>
  <groupId>com.lightbend.akka</groupId>
  <artifactId>akka-stream-alpakka-cassandra_2.11</artifactId>
  <version>0.3</version>
</dependency>

Gradle

Non-snippet tab body

Inline

For each group a directive is automatically created. This can be used for switching inline text:

Text describing the @java[Java variant]@scala[Scala variant containing ***markdown*** and @ref:[Linking](linking.md)].

Text describing the Java variantScala variant containing markdown and Linking.

Directives

You can also use groups with directives such as @@@div and @@@note as follows:

@@@ div { .group-scala }

This only shows up when the `group` is "scala"

@@@

@@@ note { .group-java }

This only shows up when the `group` is "java"

@@@

Behavior

Switching is currently done in javascript. When the page loads, a script in page.js looks for entities with class supergroup and derives the groups catalog from that. If you use a custom theme, use $page.groups$ to generate the catalog in javascript.

The currently selected group for each category is stored in a cookie.

Extending

You can register an event listener that will be called whenever a group is switched:

window.groupChanged(function(group, supergroup, catalog) {
  // your code here
});

Linking

The current group is typically determined by the order in which is was defined, or the previously-selected group as stored in a cookie. It is also possible to specify the desired group as a query parameter, so you can link to this page with Java selected or this page with Scala selected.