write intro for Syntax Highlighting; document how to create a custom adapter

- explain what source highlighting is
- explain difference between client-side and build-time syntax highlighter
- rework table that summarizes built-in syntax highlighters
- clarify that Asciidoctor does not apply syntax highlighting when producing DocBook
- add page about how to create a custom adapter

4 files changed, 120 insertions, 16 deletions

diff --git a/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb b/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb
new file mode 100644
index 00000000..8233c83e
--- /dev/null
+++ b/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb
@@ -0,0 +1,25 @@
+class PrismSyntaxHighlighter < Asciidoctor::SyntaxHighlighter::Base
+  register_for 'prism'
+
+  def format node, lang, opts
+    opts[:transform] = proc do |pre, code|
+      code['class'] = %(language-#{lang}) if lang
+    end
+    super
+  end
+
+  def docinfo? location
+    location == :footer
+  end
+
+  def docinfo location, doc, opts
+    base_url = doc.attr 'prismdir', %(#{opts[:cdn_base_url]}/prism/1.15.0)
+    slash = opts[:self_closing_tag_slash]
+    unless (theme_name = doc.attr 'prism-style', 'prism') == 'prism'
+      theme_name = %(prism-#{theme_name})
+    end
+    %(<link rel="stylesheet" href="#{base_url}/themes/#{theme_name}.min.css"#{slash}>
+<script src="#{base_url}/prism.min.js"></script>
+<script src="#{base_url}/components/prism-ruby.min.js"></script>)
+  end
+end
diff --git a/docs/modules/syntax-highlighting/nav.adoc b/docs/modules/syntax-highlighting/nav.adoc
index 7464bc7e..42bd9048 100644
--- a/docs/modules/syntax-highlighting/nav.adoc
+++ b/docs/modules/syntax-highlighting/nav.adoc
@@ -3,3 +3,4 @@
 ** xref:rouge.adoc[]
 ** xref:coderay.adoc[]
 ** xref:pygments.adoc[]
+** xref:custom.adoc[]
diff --git a/docs/modules/syntax-highlighting/pages/custom.adoc b/docs/modules/syntax-highlighting/pages/custom.adoc
new file mode 100644
index 00000000..21d600f2
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/custom.adoc
@@ -0,0 +1,22 @@
+= Custom Syntax Highlighter Adapter
+:navtitle: Custom Adapter
+
+You can integrate additional syntax highlighters by implementing a syntax highlighter adapter.
+
+To implement an adapter, you must create a class that extends the `Asciidoctor::SyntaxHighlighter::Base` class, register the adapter for a value of the `source-highlighter` attribute, and implement the required methods depending on whether the highlight step runs in the converter or in the client (i.e., browser).
+
+Here's an example of how to write and register a syntax highlighter adapter for the Prism.js syntax highlighting library.
+This library runs in the browser, so the methods focus on loading the library.
+
+.Syntax highlighter adapter for Prism.js
+[source,ruby]
+----
+include::example$syntax-highlighter-prism.rb[]
+----
+
+Save this code to a file named [.path]_syntax-highlighter-prism.rb_.
+Then require this file when invoking Asciidoctor and set the source-highlighter to prism to activate it:
+
+ $ asciidoctor -r ./syntax-highlighter-prism -a source-highlighter=prism document.adoc
+
+You can also define an adapter for a syntax highlighter that runs during conversion.
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index bc3d4222..153e0907 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -1,32 +1,88 @@
 = Syntax Highlighting
 
+AsciiDoc defines a style of listing block known as a source block for adding a source code listing to a document that's intended to be colorized by a syntax highlighter.
+Here's a simple example of a source block:
+
+[source]
+....
+[source,ruby]
+----
+puts "Hello, World!"
+----
+....
+
+Here's how we expect it to appear:
+
+[source,ruby]
+----
+puts "Hello, World!"
+----
+
+It's up to an AsciiDoc processor such as Asciidoctor to apply the syntax highlighting to this source block, a process referred to as *source highlighting*.
+Asciidoctor provides adapters that integrate with several popular syntax highlighter libraries to perform this task.
+It also provides an interface for implementing a custom syntax highlighter adapter.
+
+== Syntax highlighter types
+
+Asciidoctor supports two types of syntax highlighters: client-side and build-time.
+Let's explore each type and how they work.
+
+A *client-side* syntax highlighter performs syntax highlighting in the browser as the page is loading.
+Asciidoctor does not invoke the syntax highlighter itself.
+Instead, it focuses on adding the assets to the generated HTML so the browser can load the syntax highlighter and run it.
+For this type of syntax highlighter, Asciidoctor passes the contents of the source block through to the output as is.
+It also adds metadata to the element so that the syntax highlighter knows to highlight it and which language it is.
+Unfortunately, Asciidoctor does not process callout numbers in the source block in this case, so they may cause the syntax highlighter to get tripped up.
+
+A *build-time* syntax highlighter performs syntax highlighting during AsciiDoc conversion.
+Asciidoctor does invoke the syntax highlighter in this case.
+It also takes care of hiding the callout numbers from the syntax highlighter, ensuring they are put back in the proper place afterwards.
+What Asciidoctor emits into the output is the result produced by the syntax highlighter, which are the tokens wrapped in `<span>` tags to apply color and other formatting (either inline or via CSS classes).
+These syntax highlighters tend to support more features because Asciidoctor has greater control over the process.
+
+=== Client-side vs build-time
+
+There are benefits and drawbacks of each type.
+The benefit of a client-side syntax highlighter is that does not require installing any additional libraries.
+It also makes conversion faster and makes it produce smaller output since the syntax highlighting is deferred until page load.
+The main drawback is that callouts in the source block can be mangled by the syntax highlighter or confuse it.
+The benefits of a build-time syntax highlighter is that you have more control over syntax highlighting and can enable additional features such as line numbers and line highlighting.
+The main drawback is that it requires installing an extra library, it slows down conversion, and causes the output to be larger.
+
+You should try each syntax highlighter and find the one that works best for you.
+
+== Built-in syntax highlighter adapters
+
 [%autowidth]
 |===
-| |Syntax Highlighter |Supported Versions |Converters
+|Type |Syntax Highlighter |Required RubyGem |Compatible Converters
 
-|Client-side highlighting for source code blocks
+h|Client-side
 
 |Highlight.js
-|9.18.3
-|HTML
+|_n/a_
+|HTML, Reveal.js
 
-.3+|Server-side highlighting for source code blocks
+.3+h|Build-time
 
 |CodeRay
-|1.1.2
-|HTML
+|coderay (>= 1.1)
+|HTML, PDF, EPUB3, Reveal.js
 
 |Pygments
-|2.2.0
-|HTML
+|pygments.rb (>= 1.2)
+|HTML, PDF, EPUB3, Reveal.js
 
 |Rouge
-|3.1.1
-|HTML
+|rouge (>= 2)
+|HTML, PDF, EPUB3, Reveal.js
 |===
 
-////
-|Inline, admonition or callout font-based icons
-|Font Awesome
-|4.7
-////
+Asciidoctor does not apply syntax highlighting when generating DocBook.
+The assumption is that this is a task the DocBook toolchain can handle.
+The DocBook converter generates a `<programlisting>` tag for the source block and passes through the source language as specified in the AsciiDoc.
+It's then up to the DocBook toolchain to apply syntax highlighting to the contents of that tag.
+
+You can explore these integrations in depth on the xref:highlightjs.adoc[], xref:rouge.adoc[], xref:pygments.adoc[], and xref:coderay.adoc[] pages.
+
+You can also create your own integration by making a xref:custom.adoc[].