Snippet inclusion

@@snip block

The @@snip block is used to include code snippets from another file.

@@snip [Hello.scala](/docs/src/main/scala/Hello.scala) { #hello_example }

Inside of Hello.scala mark the desired section you want to extract using the #hello_example label as follows:

// #hello_example
object Hello extends App {
  println("hello")
}
// #hello_example

This lets us compile and test the source before including it in the documentation. The snippet is rendered with code formatting like this:

object Hello extends App {
  println("hello")
}

To display multiple snippets in a tabbed view, use definition list syntax as follows:

sbt
:   @@snip [build.sbt](/docs/src/main/resources/build.sbt) { #setup_example }

Maven
:   @@snip [pom.xml](/docs/src/main/resources/pom.xml) { #setup_example }

Gradle
:   @@snip [build.gradle](/docs/src/main/resources/build.gradle) { #setup_example }

This will be rendered like this:

sbt
libraryDependencies += "com.lightbend.akka" %% "akka-stream-alpakka-cassandra" % "0.3"
Maven
<dependency>
  <groupId>com.lightbend.akka</groupId>
  <artifactId>akka-stream-alpakka-cassandra_2.11</artifactId>
  <version>0.3</version>
</dependency>
Gradle
dependencies {
  compile group: "com.lightbend.akka", name: "akka-stream-alpakka-cassandra_2.11", version: "0.3"
}

By default, Paradox uses Prettify to highlight code and will try to detect the language of the snippet using the file extension. In cases where a snippet should not be highlighted set type=text in the directive’s attribute section:

@@snip [example.log](example.log) { #example-log type=text }

Tab Switching

It is possible to associate multiple snippets under the same “tag”. If some tab of a snippet is switched by the user, all tabs associated with the selected one will be switched as well.

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

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

Some separator.

Java
:   @@snip [example-second.java](/docs/src/main/resources/tab-switching/examples.java)

Scala
:   @@snip [example-second.scala](/docs/src/main/resources/tab-switching/examples.scala)

The result will be rendered like this (try to switch tabs):

First-java
class JavaFirst {
  public static void main(String[] args) {
    System.out.println("Hello java!");
  }
}
First-scala
object ScalaFirst extends App {
  println("Hello scala!")
}

Some separator.

Java
/*
 * Copyright © 2015 - 2019 Lightbend, Inc. <http://www.lightbend.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

class JavaSecond {
  public static void main(String[] args) {
    System.out.println("Hello java!");
  }
}
Scala
/*
 * Copyright © 2015 - 2019 Lightbend, Inc. <http://www.lightbend.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

object ScalaSecond extends App {
  println("Hello scala!")
}

This is also synced if some tabs have no snippet:

Java
/*
 * Copyright © 2015 - 2019 Lightbend, Inc. <http://www.lightbend.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

class JavaSecond {
  public static void main(String[] args) {
    System.out.println("Hello java!");
  }
}
Scala
More inline tabbing

snip.*.base_dir

In order to specify your snippet source paths off certain base directories you can define placeholders either in the page’s front matter or globally like this (for example):

paradoxProperties in Compile ++= Map(
  "snip.foo.base_dir" -> "/docs/src/main/../some/dir",
  "snip.test.base_dir" -> s"${(sourceDirectory in Test).value}/scala/org/example",
  "snip.project.base_dir" -> (baseDirectory in ThisBuild).value.getAbsolutePath
)

You can then refer to one of the defined base directories by starting the snippet’s target path with $placeholder$, for example:

@@snip [Hello.scala]($foo$/Hello.scala) { #hello_example }

@@snip [Yeah.scala]($test$/Yeah.scala) { #yeah_example }

@@snip [Yeah.scala]($root$/src/test/scala/org/example/Yeah.scala) { #yeah_example }

If a placeholder directory is relative (like $foo$ in this example) it’ll be based of the path of the respective page it is used in. Also, paradox always auto-defines the placeholder $root$ to denote the absolute path of the sbt (sub)project’s root directory.

Note: Using this feature will not allow GitHub to follow the snippet links correctly on the web UI.

Link to full source at GitHub

By default a snippet is followed by a link to the source file at Github. This can be switched off by setting snip.github_link to false.

paradoxProperties in Compile ++= Map(
  "snip.github_link" -> "false"
)
The source code for this page can be found here.