README.adoc in asciidoctor-revealjs-1.1.0 vs README.adoc in asciidoctor-revealjs-1.1.1

@@ -218,16 +218,22 @@
 
 * Setting your title to `!`
 * Adding the `notitle` option to your slide
 * Adding the `conceal` option to your slide
 
+ifeval::[{safe-mode-level} >= 20]
+See <<examples/concealed-slide-titles.adoc#,concealed-slide-titles.adoc>>.
+endif::[]
+ifeval::[{safe-mode-level} < 20]
 Here is an example of the three techniques in action:
 
-[source, asciidoc]
-----
-include::test/concealed-slide-titles.adoc[]
-----
+.concealed-slide-titles.adoc
+[source,asciidoc]
+....
+include::examples/concealed-slide-titles.adoc[lines=5..-1]
+....
+endif::[]
 
 NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to.
 
 
 === Background colors
@@ -381,11 +387,24 @@
 To override that behavior use the `width` and `height` named attributes.
 
 
 === Syntax highlighting
 
+Reveal.js is well integrated with https://highlightjs.org/[highlight.js] for syntax highlighting.
+Asciidoctor-reveal.js supports that.
+You can activate highlight.js syntax highlighting (disabled by default) by setting the `source-highlighter` document attribute as follows:
+
 [source, asciidoc]
+----
+= Presentation Title
+// [...] other document attributes
+:source-highlighter: highlightjs
+----
+
+Once enabled you can write code blocks as usual:
+
+[source, asciidoc]
 ....
 == Slide Five
 
 Uses highlighted code
 
@@ -393,11 +412,10 @@
 ----
 print "Hello World"
 ----
 ....
 
-`revealjs` uses https://highlightjs.org/[highlight.js] to do its syntax highlighting by default.
 By default `[source]` blocks and blocks delimited by `----` will be highlighted.
 An explicit `[listing]` block will not be highlighted.
 `highlight.js` does language auto-detection but using the `language="..."` attribute will hint the highlighter.
 For example this will highlight this source code as Perl:
 
@@ -410,32 +428,15 @@
 print "$0: hello world\n"
 ----
 ....
 
 [NOTE]
-Currently `revealjs` uses a rather old version of https://highlightjs.org/[highlight.js] that does not handle callouts correctly.
-To fix this download a current version of https://highlightjs.org/[highlight.js] and copy it to `reveal.js/plugin/highlight/highlight.js`.
+Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/Javascript/NPM).
+Check the `examples/` directory for examples and notes about what needs to be done for them to work.
+They are considered unsupported by the asciidoctor-reveal.js project.
 
-Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as the highlighter.
-These handle callouts correctly.
 
-To use http://coderay.rubychan.de[Coderay]:
-
-[source, asciidoc]
-----
-= Title slide
-:source-highlighter: coderay
-----
-
-To use http://pygments.org[Pygments]:
-
-[source, asciidoc]
-----
-= Title slide
-:source-highlighter: pygments
-----
-
 === Vertical slides
 
 [source, asciidoc]
 ....
 == Slide Six
@@ -461,24 +462,27 @@
 title that look like this: `:name: value`.
 
 This converter supports changing the color, image, video, iframe and
 transitions of the title slide.
 
-Read {uri-revealjs-gh}#slide-backgrounds[the relevant
-reveal.js documentation] to understand what attributes need to be set.
-Keep in mind that for title slides you must replace `data-` with
-`title-slide-`.
+Read {uri-revealjs-gh}#slide-backgrounds[the relevant reveal.js documentation] to understand what attributes need to be set.
+Keep in mind that for title slides you must replace `data-` with `title-slide-`.
 
+ifeval::[{safe-mode-level} >= 20]
+See <<examples/title-slide-image.adoc#,title-slide-image.adoc>>.
+endif::[]
+ifeval::[{safe-mode-level} < 20]
 Here is an example:
 
-[source, asciidoc]
-----
-include::test/title-slide-image.adoc[]
-----
+.title-slide-image.adoc
+[source,asciidoc]
+....
+include::examples/title-slide-image.adoc[lines=5..-1]
+....
+endif::[]
 
-The title slide is also added a `title` CSS class to help with template
-customization.
+The title slide is also added a `title` CSS class to help with template customization.
 
 === Content meant for multiple converters
 
 Some content can be created with both slides and book in mind.
 
@@ -723,9 +727,9 @@
 
 * asciidoctor 1.5.6
 
 == Copyright and Licensing
 
-Copyright (C) 2012-2017 {authors} and the Asciidoctor Project.
+Copyright (C) 2012-2018 {authors} and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
 ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]