feat(renderer): custom prefix for syntax hightlighting classes (#1028)

keeping default to 'tok-' for backward compatibility (and with Asciidoctor)

Fixes #971

Signed-off-by: Xavier Coulon <[email protected]>

README.adoc

@@ -16,7 +16,7 @@ Although it does not support the full Asciidoc/Asciidoctor syntax, Libasciidoc a
 * Document authors and revision
 * Attribute declaration and substitution
 * Paragraphs and admonition paragraphs
-* Delimited Blocks (fenced blocks, listing blocks, example blocks, comment blocks, quoted blocks, sidebar blocks, verse blocks)
+* Delimited Blocks (fenced blocks, listing blocks, example blocks, comment blocks, quoted blocks, sidebar blocks, verse blocks, open blocks)
 * Source code highlighting of delimited blocks (use either `chroma` or `pygments` as the `source-highlighter`)
 * Literal blocks (paragraph starting with a space, with the `+++....+++` delimiter or with the `[literal]` attribute)
 * Quoted text (bold, italic, monospace, marked, superscript and subscript) and substitution prevention using the backslash (`\`) character
@@ -38,11 +38,30 @@ Although it does not support the full Asciidoc/Asciidoctor syntax, Libasciidoc a
 * Table of contents
 * YAML front-matter
 
-
 See also the link:LIMITATIONS.adoc[known limitations] page for differences between Asciidoc/Asciidoctor and Libasciidoc.
 
 Further elements will be supported in the future. Feel free to open issues https://github.com/bytesparadise/libasciidoc/issues[here] to help prioritizing the upcoming work.
 
+
+=== Syntax Highlighting
+
+When enabled, syntax highlighting in `[source]` blocks is backed by the https://github.com/alecthomas/chroma[Chroma libray]. 
+The defaut class prefix is `tok-`, and it can be overridden at the document level using the `chroma-class-prefix` attribute, or from the command line interface:
+
+[source]
+----
+:chroma-class-prefix: myprefix- <1>
+:chroma-class-prefix: <2>
+----
+
+<1> classes with a custom prefix
+<2> classes without any prefix
+
+```
+$ libasciidoc -o - -a chroma-class-prefix=myprefix- mydoc.adoc
+```
+
+
 == Output Formats (backend)
 
 Using `-b` (or `--backend`) the following formats are supported:

pkg/renderer/sgml/delimited_block_source.go

@@ -106,7 +106,7 @@ func (r *sgmlRenderer) renderSourceBlockElements(ctx *renderer.Context, b *types
 		style = styles.Get(s)
 	}
 	options := []html.Option{
-		html.ClassPrefix("tok-"),
+		html.ClassPrefix(ctx.Attributes.GetAsStringWithDefault(types.AttrChromaClassPrefix, "tok-")),
 		html.PreventSurroundingPre(true),
 	}
 	// extra option: inline CSS instead of classes

pkg/renderer/sgml/html5/delimited_block_source_test.go

@@ -169,6 +169,70 @@ printf("Hello world!\n"); // <1>
 			Expect(RenderHTML(source)).To(MatchHTML(expected))
 		})
 
+		It("with highlighter with custom prefix and callouts", func() {
+			source := `:source-highlighter: chroma
+:chroma-class-prefix: myprefix-
+[source, c]
+----
+#include <stdio.h>
+
+printf("Hello world!\n"); // <1>
+<a>link</a>
+----
+<1> A greeting
+`
+			expected := `<div class="listingblock">
+<div class="content">
+<pre class="chroma highlight"><code data-lang="c"><span class="myprefix-line"><span class="myprefix-cl"><span class="myprefix-cp">#include</span> <span class="myprefix-cpf">&lt;stdio.h&gt;</span></span></span>
+
+<span class="myprefix-line"><span class="myprefix-cl"><span class="myprefix-n">printf</span><span class="myprefix-p">(</span><span class="myprefix-s">&#34;Hello world!</span><span class="myprefix-se">\n</span><span class="myprefix-s">&#34;</span><span class="myprefix-p">);</span> <span class="myprefix-c1">// 
+</span></span></span><b class="conum">(1)</b>
+<span class="myprefix-line"><span class="myprefix-cl"><span class="myprefix-o">&lt;</span><span class="myprefix-n">a</span><span class="myprefix-o">&gt;</span><span class="myprefix-n">link</span><span class="myprefix-o">&lt;/</span><span class="myprefix-n">a</span><span class="myprefix-o">&gt;</span></span></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<ol>
+<li>
+<p>A greeting</p>
+</li>
+</ol>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+
+		It("with highlighter without custom prefix and callouts", func() {
+			source := `:source-highlighter: chroma
+:chroma-class-prefix:
+[source, c]
+----
+#include <stdio.h>
+
+printf("Hello world!\n"); // <1>
+<a>link</a>
+----
+<1> A greeting
+`
+			expected := `<div class="listingblock">
+<div class="content">
+<pre class="chroma highlight"><code data-lang="c"><span class="line"><span class="cl"><span class="cp">#include</span> <span class="cpf">&lt;stdio.h&gt;</span></span></span>
+
+<span class="line"><span class="cl"><span class="n">printf</span><span class="p">(</span><span class="s">&#34;Hello world!</span><span class="se">\n</span><span class="s">&#34;</span><span class="p">);</span> <span class="c1">// 
+</span></span></span><b class="conum">(1)</b>
+<span class="line"><span class="cl"><span class="o">&lt;</span><span class="n">a</span><span class="o">&gt;</span><span class="n">link</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span></span></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<ol>
+<li>
+<p>A greeting</p>
+</li>
+</ol>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+
 		It("with other content", func() {
 			source := `----
   a<<b

pkg/types/attributes.go

@@ -20,6 +20,8 @@ const (
 	AttrDescription = "description"
 	// AttrSyntaxHighlighter the attribute to define the syntax highlighter on code source blocks
 	AttrSyntaxHighlighter = "source-highlighter"
+	// AttrChromaClassPrefix the class prefix used by Chroma when rendering source code (default: `tok-`)
+	AttrChromaClassPrefix = "chroma-class-prefix"
 	// AttrID the key to retrieve the ID
 	AttrID = "id"
 	// AttrIDPrefix the key to retrieve the ID Prefix