asciidoctor-revealjs 3.1.0 → 4.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +86 -0
  3. data/HACKING.adoc +18 -11
  4. data/README.adoc +260 -27
  5. data/Rakefile +12 -4
  6. data/asciidoctor-revealjs.gemspec +4 -2
  7. data/examples/docinfo-footer-revealjs.html +10 -0
  8. data/examples/docinfo-revealjs.html +7 -0
  9. data/examples/font-awesome.adoc +2 -1
  10. data/examples/font-awesome.css +3 -0
  11. data/examples/fragments.adoc +32 -0
  12. data/examples/fragments.css +18 -0
  13. data/examples/grid-layout-docinfo-revealjs.html +11 -0
  14. data/examples/grid-layout.adoc +174 -0
  15. data/examples/history-hash.adoc +19 -0
  16. data/examples/history-regression-tests.adoc +0 -5
  17. data/examples/history.adoc +4 -4
  18. data/examples/images/asciidoctor-logo.svg +102 -0
  19. data/examples/level-sectnums.adoc +24 -0
  20. data/examples/links-preview.adoc +32 -0
  21. data/examples/links.adoc +39 -0
  22. data/examples/release-4.0.adoc +195 -0
  23. data/examples/release-4.0.css +23 -0
  24. data/examples/source-coderay.adoc +15 -0
  25. data/examples/source-emphasis.adoc +128 -0
  26. data/examples/source-highlightjs-html.adoc +1 -1
  27. data/examples/source-highlightjs-languages.adoc +27 -0
  28. data/examples/source-highlightjs.adoc +85 -2
  29. data/examples/source-pygments.adoc +12 -0
  30. data/examples/source-rouge-docinfo.html +8 -0
  31. data/examples/source-rouge.adoc +18 -0
  32. data/examples/video.adoc +12 -3
  33. data/examples/with-docinfo-shared.adoc +13 -0
  34. data/lib/asciidoctor-revealjs/converter.rb +312 -136
  35. data/lib/asciidoctor-revealjs/highlightjs.rb +333 -2
  36. data/lib/asciidoctor-revealjs/version.rb +1 -1
  37. data/templates/asciidoctor-compatibility.css +141 -0
  38. data/templates/document.html.slim +64 -53
  39. data/templates/helpers.rb +93 -1
  40. data/templates/image.html.slim +1 -1
  41. data/templates/inline_anchor.html.slim +2 -1
  42. data/templates/inline_image.html.slim +3 -3
  43. data/templates/listing.html.slim +1 -1
  44. data/templates/section.html.slim +34 -43
  45. data/templates/stretch_nested_elements.js.slim +65 -0
  46. data/templates/title_slide.html.slim +28 -0
  47. metadata +55 -8
  48. data/examples/revealjs-features.adoc +0 -23
  49. data/templates/asciidoctor_revealjs.css.slim +0 -59
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d6ee61188a486fd610ff46c9364a470569462c8ee9b2efe321a9f036d15b3a4e
4
- data.tar.gz: adccc770637abffd5d78be47aa7f11f02fa7bbb2ac4facfa0222128529b70e14
3
+ metadata.gz: 84dae273bca0ea30c2b9fd6b4c80ced456284a3fc100d209fc353bb42d4aae6e
4
+ data.tar.gz: 6d774a5a2450f44c8d4427ae5bb0e9239bd896e508526ae677ba45b1ae6dd318
5
5
  SHA512:
6
- metadata.gz: 0ac43abbce7bb8229f6951653d85e85adb9187758e3b58b3d29e5f410a2f3b22ef4898de07e7c1c6033a1f4dac0e534716efda3e82610aa20ea4b083124ee631
7
- data.tar.gz: ff848d465227488c034f3b1347977685dffd785427faac7abfcaf33aee1249092449d2e28e185914ac8837f9ca9a97cc30b98bb92bc61b422d601b349d22f66c
6
+ metadata.gz: 7b7aa6d9c608673d06efb2abe73b9a6742321b7ff1439d294fc353cc8270bb751542ca551795a39ee581bdc96417331af75f2ec57ffc104e88012cfc36890f30
7
+ data.tar.gz: 10b2495f13043a0dc227216b80b38580377eeb84d2ada6bb4e50e291692adc39a48f8ea6f53992756203d6a2f1c2bca102fcc192f36d72dee0b5b4831d91fc1c
@@ -6,6 +6,92 @@
6
6
  This document provides a high-level view of the changes introduced in {project-name} by release.
7
7
  For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
8
8
 
9
+
10
+ == 4.0.0 (2020-02-18)
11
+
12
+ A major release with a ton of improvements!
13
+ All of reveal.js 3.8.0-3.9.2 new features are supported.
14
+ Added a new set of column layout options for quick slides design.
15
+ Highlight.js support improved.
16
+ Easier templates customizations.
17
+ New Java / JVM toolchain via [AsciidoctorJ-reveal.js](https://github.com/asciidoctor/asciidoctorj-reveal.js).
18
+ Support was added for Asciidoctor `docinfo` and `sectnums` attributes, `kbd` macro and callout styles were fixed.
19
+
20
+ See the *upgrade considerations* section for the list of potentially breaking changes.
21
+
22
+ Upgrade considerations::
23
+ * Due to an upstream change in reveal.js 3.8.0, this back-end no longer supports earlier reveal.js versions.
24
+ We added a compatibility matrix with reveal.js at the end of the README.
25
+ See {uri-issue}301[#301] for details.
26
+ * Using the attribute `background-opacity` to alter the opacity of the title slide no longer works.
27
+ When the opacity feature was introduced we forgot to align with the other title slide attributes.
28
+ The feature was introduced in 3.0.0 and the bug stayed in 3.1.0.
29
+ Starting with 4.0.0 use `title-slide-background-opacity` instead.
30
+ See issue {uri-issue}323[#323] for details.
31
+ * The new _Columns layout_ feature required a new `<div>` that wraps all slide content (everything except the slide title).
32
+ This might impact custom CSS with strict child relationships.
33
+ See issue {uri-issue}326[#326] and PR {uri-issue}332[#332] for details.
34
+ * We bundle Highlight.js instead of relying on reveal.js.
35
+ We reduced the core set of supported languages and added the `highlightjs-languages` attribute to add specific languages on demand.
36
+ Depending on what type of code you were highlighting, you might need to add your language using that attribute.
37
+ See {uri-issue}320[#320] for details.
38
+ * Our support of AsciiDoc `docinfo` attribute changed.
39
+ We were previously injecting `docinfo-header.html` somewhere in the HTML `<head>`.
40
+ Now, `docinfo-revealjs.html` goes last into the HTML `<head>`, `docinfo-header-revealjs.html` goes right before the first slide `<section>` and `docinfo-footer-revealjs.html` goes right after the last slide `<section>`.
41
+ The new documentation is available https://github.com/asciidoctor/asciidoctor-reveal.js#supplemental-content-with-docinfo[here] and the related tickets are {uri-issue}198[#198] and {uri-issue}324[#324].
42
+ * Default highlight.js theme is monokai. This follows a reveal.js change.
43
+
44
+ Enhancements::
45
+ * New _Columns layout_ feature which provides easy to use roles to create multiple columns in slides.
46
+ See the https://github.com/asciidoctor/asciidoctor-reveal.js#columns-layout[feature's documentation] for usage details.
47
+ See issue {uri-issue}326[#326] and PRs {uri-issue}332[#332], {uri-issue}340[#340] for details.
48
+ * Built-in slim templates can now be overridden with `--template-dir` or `-T` ({uri-issue}177[#177], {uri-issue}318[#318])
49
+ * Highlight.js is now bundled by us instead of reveal.js.
50
+ You can add other languages not supported in the core set by using the `highlightjs-languages` attribute.
51
+ It can also be loaded locally or from a CDN of your choice.
52
+ See issues {uri-issue}21[#21], {uri-issue}319[#319] and {uri-issue}320[#320] for details.
53
+ * We now support the Java / JVM ecosystem.
54
+ This packaging happens in a separate project: https://github.com/asciidoctor/asciidoctorj-reveal.js[AsciidoctorJ reveal.js].
55
+ See issue {uri-issue}271[#217] and PR {uri-issue}337[#337] for details.
56
+ * Many new examples demonstrating various features
57
+ * Documentation improvements ({uri-issue}322[#322])
58
+ * Refactoring ({uri-issue}327[#327], {uri-issue}330[#330], {uri-issue}333[#333])
59
+
60
+ Compliance::
61
+ * New reveal.js 3.8.0 and 3.9.0 features supported ({uri-issue}301[#301])
62
+ ** Line numbers on source code blocks using Asciidoctor's `linenums` attribute
63
+ ** Specific lines and step-by-step code highlights using Asciidoctor's `highlight` attribute
64
+ ** reveal.js `data-preview` on links and images with link can be activated by using the `preview` and `link_preview` Asciidoctor attributes respectively
65
+ ** New configuration options: `hash`, `navigationMode`, `shuffle`, `preloadIframes`, `totalTime`, `minimumTimePerSlide`, `hideInactiveCursor`, `hideCursorTime`, `previewLinks` (`data-preview-link`) and `mobileViewDistance` ({uri-issue}301[#301])
66
+ * Added support for the `sectnums` AsciiDoc attribute ({uri-issue}185[#185], {uri-issue}317[#317])
67
+ * Aligned our `docinfo` support to Asciidoctor Bespoke ({uri-issue}198[#198], {uri-issue}324[#324])
68
+ * Support the `highlightjs-languages` attribute from Asciidocotor ({uri-issue}319[#319], {uri-issue}320[#320])
69
+ * `background-opacity` title slide attribute renamed to `title-slide-background-opacity` ({uri-issue}323[#323], {uri-issue}325[#325])
70
+ * Added support for the `kdb` macro to represent keyboard shortcuts ({uri-issue}276[#276], {uri-issue}329[#329])
71
+ * Cosmetic improvements to callout lists ({uri-issue}335[#335])
72
+
73
+ Bug Fixes::
74
+ * Line height CSS fix with code listing with line numbers ({uri-issue}331[#331], {uri-issue}334[#334])
75
+ * Interactive debugging works again ({uri-issue}322[#322])
76
+ * Fixed _Uncaught ReferenceError: require is not defined_ by dropping outdated documentation ({uri-issue}344[#344])
77
+
78
+ === Release meta
79
+
80
+ * Released on: 2020-02-18
81
+ * Released by: Olivier Bilodeau
82
+ * Release drink: https://defi.leclub28.com/en/p/47E2C422178348F[Lime Flavored Sparkling Water]
83
+
84
+ {uri-repo}/releases/tag/v4.0.0[git tag] |
85
+ {uri-repo}/compare/v3.1.0...v4.0.0[full diff] |
86
+ {uri-repo}/milestone/8[milestone]
87
+
88
+ === Credits
89
+
90
+ Thanks to the following people who contributed to this release:
91
+
92
+ Guillaume Grossetie, thomas and Olivier Bilodeau
93
+
94
+
9
95
  == 3.1.0 (2020-01-18)
10
96
 
11
97
  Fixed a regression with Font-Awesome brand icons, added a JavaScript CLI and standalone executables for Windows, Linux and macOS.
@@ -30,9 +30,8 @@ Two complementary approaches can be used to explore the context offered by ascii
30
30
 
31
31
  [NOTE]
32
32
  --
33
- Starting with v1.1.0 the slim templates are compiled to Ruby in order to
34
- use the same templates from Asciidoctor.js (Javascript / Node.js ecosystem).
35
- Don't forget to recompile the templates if you make changes to them.
33
+ Debugging is only supported via the Ruby ecosystem.
34
+ You need to recompile the templates when you make changes to them.
36
35
  This can be done by running:
37
36
 
38
37
  bundle exec rake build
@@ -80,6 +79,10 @@ In order to be dropped into the debugger at a specific point in a template simpl
80
79
  - binding.pry
81
80
  ----
82
81
 
82
+ Recompile the templates with:
83
+
84
+ bundle exec rake build
85
+
83
86
  Then run `asciidoctor-revealjs` from the command-line to generate your document and you'll be dropped in the debugger:
84
87
 
85
88
  ----
@@ -111,13 +114,11 @@ You can also query asciidoctor's documentation:
111
114
  If you install the `pry-byebug` gem you get additional debugging capabilities.
112
115
  See the gem's documentation for details.
113
116
 
114
- Since 1.1.0, templates are compiled. It is easier to inject the debug
115
- triggering statements and use the templates directly instead of debugging
116
- compiled templates. You can call the slim templates directly with:
117
+ Since 1.1.0, templates are compiled.
118
+ It is easier to inject the debug triggering statements and use the templates directly instead of debugging compiled templates.
119
+ You can call the slim templates directly with:
117
120
 
118
- // TODO it's still not clear whether `-r slim-htag` is required right now (#153)
119
-
120
- bundle exec asciidoctor --trace -T templates/ examples/customcss.adoc
121
+ bundle exec asciidoctor-revealjs --trace -T templates/ examples/customcss.adoc
121
122
 
122
123
  === References
123
124
 
@@ -306,13 +307,14 @@ Then run:
306
307
  == Release process
307
308
 
308
309
 
310
+ . Make sure that the highlight plugin code embed in _lib/asciidoctor-revealjs/highlightjs.rb_ is up-to-date with the version of reveal.js
309
311
  . Do we need to do anything regarding our Opal dependency and Asciidoctor.js?
310
312
  See <<node-binary-compatibility,our section on the topic>>.
311
313
  . Update dependencies and test the package in both languages
312
314
  +
313
315
  bundle update
314
316
  bundle exec rake build
315
- bundle exec rake doctest
317
+ bundle exec rake test
316
318
  bundle exec rake examples:convert
317
319
  npm update --no-save
318
320
  bundle exec rake build:js
@@ -366,7 +368,8 @@ Then run:
366
368
  . Check that the new version is available on https://www.npmjs.com/package/@asciidoctor/reveal.js[npmjs.com]
367
369
  . Make binaries release
368
370
  ** Run `npm run package`. Binaries built will be in `dist/`. Upload them to the GitHub release page.
369
- . Update version in `lib/asciidoctor-revealjs/version.rb` and `package.json` (+1 bugfix and append '-dev') and commit
371
+ . Publish previously saved GitHub release draft
372
+ . Update version in `lib/asciidoctor-revealjs/version.rb` and `package.json` (+1 bugfix and append '-dev')
370
373
  ** Remove the "Slim compiled to Ruby" converter to the git tree (to avoid noise to the repo and `git status` noise)
371
374
  +
372
375
  git rm --cached lib/asciidoctor-revealjs/converter.rb
@@ -374,6 +377,10 @@ Then run:
374
377
  ** commit msg: Begin development on next release
375
378
  . Submit a PR upstream to sync the documentation on asciidoctor.org
376
379
  ** Modify this page: https://github.com/asciidoctor/asciidoctor.org/edit/master/docs/asciidoctor-revealjs.adoc
380
+ . Submit a PR downstream to update Asciidoctor reveal.js version inside docker-asciidoctor
381
+ ** Modify the `Dockerfile`, `Makefile` and `README.adoc` of: https://github.com/asciidoctor/docker-asciidoctor
382
+ . Submit a PR downstream to update AsciidoctorJ reveal.js version
383
+ ** Modify `gradle.properties`, `asciidoctorj-revealjs/gradle.properties` and `asciidoctorj-revealjs/build.gradle` in: https://github.com/asciidoctor/asciidoctorj-reveal.js
377
384
 
378
385
  == Ruby and asciidoctor-doctest tests
379
386
 
@@ -21,7 +21,7 @@ endif::[]
21
21
  :uri-revealjs-home: http://lab.hakim.se/reveal-js/
22
22
  :uri-revealjs-gh: https://github.com/hakimel/reveal.js
23
23
  :uri-nodejs-download: https://nodejs.org/en/download/
24
- :showcasedir: showcase
24
+ :showcasedir: showcase
25
25
 
26
26
  ifdef::env-github[]
27
27
  image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js]
@@ -34,16 +34,19 @@ endif::[]
34
34
 
35
35
  TIP: Want to see some example presentations, see <<Showcase Presentations>>
36
36
 
37
- There are three main technology stacks that can transform AsciiDoc into HTML5 / reveal.js:
37
+ There are four main technology stacks that can convert AsciiDoc into HTML5 / reveal.js:
38
38
 
39
39
  * Asciidoctor / Ruby / Bundler (See <<Ruby Setup>>)
40
40
  * Asciidoctor.js / JavaScript (Node.js) / npm (See <<Node / JavaScript Setup>>)
41
41
  * Standalone Executable (See <<Standalone Executable>>)
42
+ * AsciidoctorJ / JVM / Maven (See https://github.com/asciidoctor/asciidoctorj-reveal.js[this project])
42
43
 
43
44
  ifeval::['{branch}' == 'master']
44
45
  NOTE: You're viewing the documentation for an upcoming release.
45
46
  If you're looking for the documentation for the current release or an older one, please click on the appropriate link below: +
46
- {uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest release)
47
+ {uri-project-repo}/tree/v3.1.0#readme[3.1.0] (latest release)
48
+ &hybull;
49
+ {uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest from 2.x series)
47
50
  &hybull;
48
51
  {uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest from 1.1 series)
49
52
  &hybull;
@@ -106,7 +109,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
106
109
  . Optional: Copy or clone reveal.js presentation framework.
107
110
  Allows you to modify themes or view slides offline.
108
111
 
109
- $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git
112
+ $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
110
113
 
111
114
 
112
115
  === Rendering the AsciiDoc into slides
@@ -117,7 +120,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
117
120
  . Generate HTML presentation from the AsciiDoc source
118
121
 
119
122
  $ bundle exec asciidoctor-revealjs \
120
- -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 CONTENT_FILE.adoc
123
+ -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@3.9.2 CONTENT_FILE.adoc
121
124
 
122
125
  . If you did the optional step of having a local reveal.js clone you can
123
126
  convert AsciiDoc source with
@@ -229,7 +232,7 @@ The executables are built using the <<Node / JavaScript Setup,Node / JavaScript>
229
232
  * Copy or clone the reveal.js presentation framework in the directory where you will build your slidedeck.
230
233
  Here we do a shallow clone of the repo:
231
234
 
232
- $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git
235
+ $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
233
236
 
234
237
  === Convert AsciiDoc into slides
235
238
 
@@ -528,9 +531,9 @@ To override that behavior use the `width` and `height` named attributes.
528
531
 
529
532
  === Syntax highlighting
530
533
 
531
- Reveal.js is well integrated with https://highlightjs.org/[highlight.js] for syntax highlighting.
532
- Asciidoctor-reveal.js supports that.
533
- You can activate highlight.js syntax highlighting (disabled by default) by setting the `source-highlighter` document attribute as follows:
534
+ reveal.js is well integrated with https://highlightjs.org/[Highlight.js] for syntax highlighting.
535
+ Asciidoctor reveal.js supports that.
536
+ You can activate Highlight.js syntax highlighting (disabled by default) by setting the `source-highlighter` document attribute as follows:
534
537
 
535
538
  [source, asciidoc]
536
539
  ----
@@ -539,7 +542,26 @@ You can activate highlight.js syntax highlighting (disabled by default) by setti
539
542
  :source-highlighter: highlightjs
540
543
  ----
541
544
 
542
- Once enabled you can write code blocks as usual:
545
+ [NOTE]
546
+ ----
547
+ By default, we are using a prebuilt version of Highlight.js with 34 commonly used languages hosted on https://cdnjs.com/[cdnjs].
548
+ You can load additionnal languages using the `:highlightjs-languages:` attribute:
549
+
550
+ ```
551
+ // load yaml and scilab languages
552
+ :highlightjs-languages: yaml, scilab
553
+ ```
554
+
555
+ You can also load Highlight.js from a custom base directory (or remote URL) using the `:highlightjsdir:` attribute:
556
+
557
+ ```
558
+ // load from a local path
559
+ :highlightjsdir: highlight
560
+ // load from jsdelivr CDN
561
+ //:highlightjsdir: https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.18.0/build
562
+ ----
563
+
564
+ Once enabled, you can write code blocks as usual:
543
565
 
544
566
  [source, asciidoc]
545
567
  ....
@@ -569,7 +591,8 @@ print "$0: hello world\n"
569
591
  ....
570
592
 
571
593
  [NOTE]
572
- 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).
594
+ Alternatively, you can use http://rouge.jneen.net/[Rouge], http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters,
595
+ if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/JavaScript/npm).
573
596
  Check the `examples/` directory for examples and notes about what needs to be done for them to work.
574
597
  They are considered unsupported by the asciidoctor-reveal.js project.
575
598
 
@@ -592,8 +615,106 @@ Slide Six.One will be rendered vertically below Slide Six.
592
615
  Here is {uri-revealjs-gh}#markup[the relevant reveal.js
593
616
  documentation] on that topic.
594
617
 
618
+ === Columns layout
619
+
620
+ Inspired by https://bulma.io/[Bulma], Asciidoctor reveal.js supports columns layout out-of-the-box:
621
+
622
+ [source, asciidoc]
623
+ ....
624
+ [.columns]
625
+ == 2 columns
626
+
627
+ [.column]
628
+ --
629
+ * **Edgar Allen Poe**
630
+ * Sheri S. Tepper
631
+ * Bill Bryson
632
+ --
633
+
634
+ [.column]
635
+ --
636
+ Edgar Allan Poe (/poʊ/; born Edgar Poe; January 19, 1809 – October 7, 1849) was an American writer, editor, and literary critic.
637
+ --
638
+ ....
639
+
640
+ If you do not specify a size, each column will have an equal width, no matter the number of columns.
641
+
642
+ [source, asciidoc]
643
+ ....
644
+ [.columns]
645
+ == 3 columns
646
+
647
+ [.column]
648
+ * Java
649
+ * **Kotlin**
650
+
651
+ [.column]
652
+ * Node
653
+ * **Deno**
654
+
655
+ [.column]
656
+ * Ruby
657
+ * **Crystal**
658
+ ....
659
+
660
+ If you want to change the size of a single column, you can use one of the following classes:
595
661
 
596
- === Asciidoctor-reveal.js specific roles
662
+ * `is-three-quarters`
663
+ * `is-two-thirds`
664
+ * `is-half`
665
+ * `is-one-third`
666
+ * `is-one-quarter`
667
+ * `is-full`
668
+
669
+ The other columns will fill up the remaining space automatically. +
670
+ You can use the following multiples of 20% as well:
671
+
672
+ * `is-four-fifths`
673
+ * `is-three-fifths`
674
+ * `is-two-fifths`
675
+ * `is-one-fifth`
676
+
677
+ [source, asciidoc]
678
+ ....
679
+ [.columns]
680
+ == Columns with size
681
+
682
+ [.column.is-one-third]
683
+ --
684
+ * **Kotlin**
685
+ * Java
686
+ * Scala
687
+ --
688
+
689
+ [.column]
690
+ --
691
+ Programming language for Android, mobile cross-platform
692
+ and web development, server-side, native,
693
+ and data science. Open source forever Github.
694
+ --
695
+ ....
696
+
697
+ The vertical alignment of columns defaults to top aligned.
698
+ Content can be centered by adding the `is-vcentered` class to the slide.
699
+
700
+ [source, asciidoc]
701
+ ....
702
+ [.columns.is-vcentered]
703
+ == Columns Vertically Centered
704
+
705
+ [.column]
706
+ --
707
+ * Few
708
+ * Bullets
709
+ * Here
710
+ --
711
+
712
+ [.column]
713
+ image::large-image.png[]
714
+ ....
715
+
716
+
717
+ === Asciidoctor reveal.js specific roles
597
718
 
598
719
  Roles are usually applied with the following syntax where the `important-text` CSS class would be applied to the slide title in the generated HTML:
599
720
 
@@ -628,6 +749,17 @@ Here is a list of supported roles:
628
749
  right:: Will apply a `float: right` style to the affected block
629
750
 
630
751
 
752
+ === Asciidoctor reveal.js specific attributes
753
+
754
+ ==== iFrame Preview Overlay
755
+
756
+ The reveal.js feature activated by a global `previewLinks: true` configuration or by adding the `data-preview-link` HTML attribute to `<a>` tags can be activated by using special AsciiDoc attributes.
757
+
758
+ On links use the `preview=true` attribute, on images use the `link_preview=true` attribute and globally you can set `:revealjs_previewlinks:` attribute.
759
+
760
+ See <<examples/links.adoc#,links.adoc>> and <<examples/links-preview.adoc#,links-preview.adoc>> for examples.
761
+
762
+
631
763
  === Title slide customization
632
764
 
633
765
  The title slide is customized via Asciidoc attributes.
@@ -763,6 +895,41 @@ WARNING: This presentation is dangerous!
763
895
 
764
896
  Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support.
765
897
 
898
+ === Supplemental Content with Docinfo
899
+ // Originally from https://github.com/asciidoctor/asciidoctor-bespoke#supplemental-content
900
+
901
+ It's possible to inject supplemental content into the output document using http://asciidoctor.org/docs/user-manual/#docinfo-file[docinfo files].
902
+ This core feature of AsciiDoc has been adapted to work with the reveal.js converter.
903
+
904
+ Currently, there are three insertion locations for docinfo content in a reveal.js document:
905
+
906
+ head:: content is inserted after the last child of the `<head>` element
907
+ header:: content is inserted before the first child of the `<div class="slides">` element (before the slides)
908
+ footer:: content is inserted after the last child of the `<div class="slides">` element (after the slides)
909
+
910
+ The content you want to insert goes into a sibling file of the slide deck document with the following filename patterns:
911
+
912
+ head:: `docinfo-revealjs.html`
913
+ header:: `docinfo-header-revealjs.html`
914
+ footer:: `docinfo-footer-revealjs.html`
915
+
916
+ For example, let's say you want to embed a tweet into your slide deck.
917
+ You might inject the shared embedding JavaScript using a footer docinfo file:
918
+
919
+ .src/docinfo-footer-revealjs.html
920
+ [source,html]
921
+ ----
922
+ <script src="https://platform.twitter.com/widgets.js"></script>
923
+ ----
924
+
925
+ You then need to set the following document attribute in the AsciiDoc header:
926
+
927
+ ----
928
+ :docinfo: shared
929
+ ----
930
+
931
+ When this attribute is defined, the converter will automatically read the docinfo file(s) and insert the contents into the specified location in the output document.
932
+
766
933
 
767
934
  == Reveal.js Options
768
935
 
@@ -794,7 +961,7 @@ Default is built-in [path]_lib/css/zenburn.css_.
794
961
  |<file\|URL>
795
962
  |Overrides reveal.js directory.
796
963
  Example: ../reveal.js or
797
- https://cdnjs.com/libraries/reveal.js/3.7.0[https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0].
964
+ https://cdn.jsdelivr.net/npm/reveal.js@3.9.2.
798
965
  Default is `reveal.js/` unless in a Node.js environment where it is `node_modules/reveal.js/`.
799
966
 
800
967
  |:revealjs_controls:
@@ -836,9 +1003,13 @@ all:: show on all views (default)
836
1003
  speaker:: only show slide numbers on speaker notes view
837
1004
  print:: only show slide numbers when printing to PDF
838
1005
 
1006
+ |:revealjs_hash:
1007
+ |true, *false*
1008
+ |Add the current slide number to the URL hash so that reloading the page/copying the URL will return you to the same slide
1009
+
839
1010
  |:revealjs_history:
840
1011
  |true, *false*
841
- |Push each slide change to the browser history.
1012
+ |Push each slide change to the browser history. Implies `hash: true`
842
1013
 
843
1014
  |:revealjs_keyboard:
844
1015
  |*true*, false
@@ -864,6 +1035,14 @@ print:: only show slide numbers when printing to PDF
864
1035
  |true, *false*
865
1036
  |Change the presentation direction to be RTL.
866
1037
 
1038
+ |:revealjs_navigationMode:
1039
+ |*default*, linear, grid
1040
+ |See https://github.com/hakimel/reveal.js/#navigation-mode for details
1041
+
1042
+ |:revealjs_shuffle:
1043
+ |true, *false*
1044
+ |Randomizes the order of slides each time the presentation loads
1045
+
867
1046
  |:revealjs_fragments:
868
1047
  |*true*, false
869
1048
  |Turns fragments on and off globally.
@@ -892,6 +1071,14 @@ null:: Media will only autoplay if data-autoplay is present
892
1071
  true:: All media will autoplay, regardless of individual setting
893
1072
  false:: No media will autoplay, regardless of individual setting
894
1073
 
1074
+ |:revealjs_preloadIframes:
1075
+ |*null*, true, false
1076
+ a|Global override for preloading lazy-loaded iframes
1077
+
1078
+ null:: Iframes with `data-src` AND `data-preload` will be loaded when within the `viewDistance`, iframes with only `data-src` will be loaded when visible
1079
+ true:: All iframes with `data-src` will be loaded when within the `viewDistance`
1080
+ false:: All iframes with `data-src` will be loaded only when visible
1081
+
895
1082
  |:revealjs_autoSlide:
896
1083
  |<integer>
897
1084
  |Delay in milliseconds between automatically proceeding to the next slide.
@@ -912,10 +1099,31 @@ This value can be overwritten by using a `data-autoslide` attribute on your slid
912
1099
  This is used to show a pacing timer in the speaker view.
913
1100
  Defaults to *120*
914
1101
 
1102
+ |:revealjs_totalTime:
1103
+ |<integer>
1104
+ |Specify the total time in seconds that is available to present.
1105
+ If this is set to a nonzero value, the pacing timer will work out the time available for each slide, instead of using the defaultTiming value.
1106
+ Defaults to *0*
1107
+
1108
+ |:revealjs_minimumTimePerSlide:
1109
+ |<integer>
1110
+ |Specify the minimum amount of time you want to allot to each slide, if using the totalTime calculation method.
1111
+ If the automated time allocation causes slide pacing to fall below this threshold, then you will see an alert in the speaker notes window.
1112
+ Defaults to *0*.
1113
+
915
1114
  |:revealjs_mouseWheel:
916
1115
  |true, *false*
917
1116
  |Enable slide navigation via mouse wheel.
918
1117
 
1118
+ |:revealjs_hideInactiveCursor:
1119
+ |*true*, false
1120
+ |Hide cursor if inactive
1121
+
1122
+ |:revealjs_hideCursorTime:
1123
+ |<integer>
1124
+ |Time before the cursor is hidden (in ms).
1125
+ Defaults to *5000*.
1126
+
919
1127
  |:revealjs_hideAddressBar:
920
1128
  |*true*, false
921
1129
  |Hides the address bar on mobile devices.
@@ -923,7 +1131,7 @@ Defaults to *120*
923
1131
  |:revealjs_previewLinks:
924
1132
  |true, *false*
925
1133
  |Opens links in an iframe preview overlay.
926
- Add `data-preview-link` and `data-preview-link="false"` to customise each link individually
1134
+ Add the `preview=true` attribute on links or `link_preview=true` attribute on images to customize each link individually.
927
1135
 
928
1136
  |:revealjs_transition:
929
1137
  |none, fade, *slide*, convex, concave, zoom
@@ -939,7 +1147,14 @@ Add `data-preview-link` and `data-preview-link="false"` to customise each link i
939
1147
 
940
1148
  |:revealjs_viewDistance:
941
1149
  |<integer>
942
- |Number of slides away from the current that are visible. Default: 3
1150
+ |Number of slides away from the current that are visible.
1151
+ Default: *3*.
1152
+
1153
+ |:revealjs_mobileViewDistance:
1154
+ |<integer>
1155
+ |Number of slides away from the current that are visible on mobile devices.
1156
+ It is advisable to set this to a lower number than viewDistance in order to save resources.
1157
+ Default *3*.
943
1158
 
944
1159
  |:revealjs_parallaxBackgroundImage:
945
1160
  |<file\|URL>
@@ -1001,6 +1216,13 @@ look at the
1001
1216
  theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to
1002
1217
  activate it.
1003
1218
 
1219
+
1220
+ === PDF Export
1221
+
1222
+ Follow https://github.com/hakimel/reveal.js#pdf-export[reveal.js' documentation] for PDF export.
1223
+ We would add that we have successfully used PDF export without the requirement of a Web server.
1224
+
1225
+
1004
1226
  === Default plugins
1005
1227
 
1006
1228
  By default, generated presentations will have the following reveal.js plugins enabled:
@@ -1019,17 +1241,6 @@ For example, to disable all the default plugins set the following document attri
1019
1241
  :revealjs_plugin_notes: disabled
1020
1242
  ----
1021
1243
 
1022
- reveal.js ships with a plugin that allows to create a PDF from a slide deck.
1023
- To enable this plugin, set the `revealjs_plugin_pdf` attribute.
1024
-
1025
- ----
1026
- :revealjs_plugin_pdf: enabled
1027
- ----
1028
-
1029
- When the plugin is enabled and you run your presentation in a browser with `?print-pdf` at the end of the URL, you can then use the default print function to print the slide deck into a PDF document.
1030
-
1031
- TIP: To work properly, this plugin requires a Chrome-based browser.
1032
-
1033
1244
 
1034
1245
  === Additional plugins
1035
1246
 
@@ -1059,6 +1270,28 @@ If you need more details about our dependencies check out Asciidoctor dependenci
1059
1270
  * With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10
1060
1271
  * With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3
1061
1272
 
1273
+
1274
+ [[revealjs-compatibility-matrix]]
1275
+ == reveal.js Compatibility Matrix
1276
+
1277
+ We try as much as possible to be compatible with a broad range of reveal.js versions.
1278
+ However, changes made by that project sometimes forces us to drop compatibility with older reveal.js releases.
1279
+ This table tracks this compatibility.
1280
+
1281
+ |===
1282
+ |Asciidoctor reveal.js version |reveal.js version
1283
+
1284
+ |4.x
1285
+ |3.9 - 3.8
1286
+
1287
+ |3.x, 2.x, 1.x
1288
+ |3.7 - 3.0
1289
+
1290
+ |Unversioned releases
1291
+ |2.x
1292
+ |===
1293
+
1294
+
1062
1295
  [[asciidoctorjs-compatibility-matrix]]
1063
1296
  == Asciidoctor.js Compatibility Matrix
1064
1297