https://github.com/bmuschko/asciidoctorj-tabbed-code-extension

An AsciidoctorJ extension for rendering code on multiple tabs.
https://github.com/bmuschko/asciidoctorj-tabbed-code-extension

Last synced: 7 days ago
JSON representation

An AsciidoctorJ extension for rendering code on multiple tabs.

• Host: GitHub
• URL: https://github.com/bmuschko/asciidoctorj-tabbed-code-extension
• Owner: bmuschko
• License: apache-2.0
• Created: 2018-11-15T01:13:41.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2021-03-10T20:01:29.000Z (over 3 years ago)
• Last Synced: 2023-07-26T21:23:09.013Z (over 1 year ago)
• Language: Java
• Size: 180 KB
• Stars: 16
• Watchers: 2
• Forks: 6
• Open Issues: 1
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
= AsciidoctorJ tabbed code extension image:https://travis-ci.org/bmuschko/asciidoctorj-tabbed-code-extension.svg?branch=master["Build Status", link="https://travis-ci.org/bmuschko/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.

image::images/tabbed-code-groovy.png[Groovy tab,500]

image::images/tabbed-code-kotlin.png[Kotlin tab,500]

== Using the extension

All you need to do to use the extension is to add it to the link:https://repo1.maven.org/maven2/com/bmuschko/asciidoctorj-tabbed-code-extension/[dependency from Maven Central]. The following two examples demonstrate the use of version 0.3 from Maven and Gradle.

.pom.xml

[source,xml]

----

    com.bmuschko

    asciidoctorj-tabbed-code-extension

    0.3

    runtime

----

.build.gradle.kts

[source,groovy]

----

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]

....

[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 https://zeptojs.com/[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`  |https://github.com/bmuschko/asciidoctorj-tabbed-code-extension/blob/master/src/main/resources/codeBlockSwitch.js[`/codeBlockSwitch.js`] |The JavaScript controlling the behavior read from the runtime classpath.

|`tabbed-code-css-path` |https://github.com/bmuschko/asciidoctorj-tabbed-code-extension/blob/master/src/main/resources/codeBlockSwitch.css[`/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

[source,kotlin]

----

tasks.named("asciidoctor") {

    sourceDir = file("src/docs/asciidoc")

    sources(delegateClosureOf {

        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"

        )

    )

}

----