AsciidoctorJ tabbed code extension

This AsciidoctorJ extension can render code on multiple tabs. The functionality is particularly useful if you want to demonstrate a code example in different languages or tools, as shown in the following two images.

Using the extension

All you need to do to use the extension is to add it to the dependency from Maven Central. The following two examples demonstrate the use of version 0.3 from Maven and Gradle.

pom.xml

<dependency>
    <groupId>com.bmuschko</groupId>
    <artifactId>asciidoctorj-tabbed-code-extension</artifactId>
    <version>0.3</version>
    <scope>runtime</scope>
</dependency>

build.gradle.kts

dependencies {
    runtimeOnly("com.bmuschko:asciidoctorj-tabbed-code-extension:0.3")
}

Important

This extension is based on AsciidoctorJ version 2.0.0. Make sure that the consuming project uses that exact version (or greater) to avoid incompatibilities. If you need a version compatible with an older version of AsciidoctorJ (down to 1.6.0-RC1) then use version 0.2 of this extension.

To use the extension in Asciidoc provide code blocks with different roles. Specify the primary role for the code block that should appear in the first, topmost tab to the left and use the secondary role for all other tabs. The extension uses the title of the code block for rendering the tab label.

[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
docker {
    registryCredentials {
        url = 'https://gcr.io'
        username = '_json_key'
        password = file('keyfile.json').text
    }
}
----

[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
docker {
    registryCredentials {
        url.set("https://gcr.io")
        username.set("_json_key")
        password.set(file("keyfile.json").readText())
    }
}
----

Configuring the extension

Under the hood, the extension uses the JavaScript library Zepto.js. Currently, the JavaScript library is not configurable.

By default, the extension provides a JavaScript and CSS file that already takes care of the runtime behavior and styling. The runtime behavior and styling is configurable. The table below shows the attributes that allow you to configure the extension.

Attribute	Default Value	Description
`tabbed-code-js-path`	`/codeBlockSwitch.js`	The JavaScript controlling the behavior read from the runtime classpath.
`tabbed-code-css-path`	`/codeBlockSwitch.css`	The CSS controlling the styling read from the runtime classpath.

The following example shows how to use the CSS attributes to provide custom styling in a Gradle build using the Kotlin DSL.

build.gradle.kts

tasks.named<AsciidoctorTask>("asciidoctor") {
    sourceDir = file("src/docs/asciidoc")
    sources(delegateClosureOf<PatternSet> {
        include("index.adoc")
    })

    attributes(
        mapOf(
            "toc" to "left",
            "source-highlighter" to "prettify",
            "icons" to "font",
            "numbered" to "",
            "idprefix" to "",
            "docinfo1" to "true",
            "sectanchors" to "true",
            "tabbed-code-css-path" to "/customTabbedCode.css"
        )
    )
}

Additional Tab-like Button Appears when Using Tabbed Code Blocks

Hello Benjamin,
First of all thanks for this great extension, started to use it a couple of months ago.

However, we faced with a weird thing as shown in the below screenshots:

When I investigated using the "Inspect" tool of Google Chrome, I saw the below extra "div" just above the real "div"s:

<div class="switch">
  <div class="switch--item selected">
  </div>
</div>

And I can't get rid of it.

Here is my related lines in the build.gradle file:

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.7'
        classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.16'
        classpath 'org.asciidoctor:asciidoctorj-epub3:1.5.0-alpha.8.1'
        classpath 'org.asciidoctor:asciidoctorj:1.6.0'
    }
}

repositories {
    mavenCentral()
    ........
    maven {
        url  "https://dl.bintray.com/bmuschko/maven" 
    }

}

dependencies {
     ........
     asciidoctor 'com.bmuschko:asciidoctorj-tabbed-code-extension:0.2'
}

And here is an example on how I use the extension in a source Asciidoc file:

[source,shell,indent=0,subs="verbatim,attributes",role="primary"]
.Linux
----
some code
----

[source,shell,indent=0,subs="verbatim,attributes",role="secondary"]
.Windows
----
some other code
----

[source,shell,indent=0,subs="verbatim,attributes",role="secondary"]
.Docker
----
a whole another code
----

We'd more than glad if you can comment or help. Do you have any thoughts on this?

Thanks a lot in advance.

bmuschko / asciidoctorj-tabbed-code-extension Goto Github PK