asciidoctor-revealjs 1.1.3 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (76) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +72 -0
  3. data/Gemfile +2 -0
  4. data/HACKING.adoc +29 -14
  5. data/LICENSE.adoc +1 -1
  6. data/README.adoc +239 -23
  7. data/Rakefile +22 -1
  8. data/asciidoctor-revealjs.gemspec +6 -4
  9. data/examples/background-color.adoc +45 -0
  10. data/examples/background-color.css +18 -0
  11. data/examples/history-regression-tests.adoc +12 -2
  12. data/examples/images.adoc +32 -0
  13. data/examples/revealjs-features.adoc +23 -0
  14. data/examples/revealjs-plugin-activation.adoc +16 -0
  15. data/examples/revealjs-plugins-conf.js +10 -0
  16. data/examples/revealjs-plugins.adoc +16 -0
  17. data/examples/revealjs-plugins.js +2 -0
  18. data/examples/revealjs-plugins/chalkboard/README.md +124 -0
  19. data/examples/revealjs-plugins/chalkboard/chalkboard.js +1288 -0
  20. data/examples/revealjs-plugins/chalkboard/img/blackboard.png +0 -0
  21. data/examples/revealjs-plugins/chalkboard/img/boardmarker.png +0 -0
  22. data/examples/revealjs-plugins/chalkboard/img/chalk.png +0 -0
  23. data/examples/revealjs-plugins/chalkboard/img/sponge.png +0 -0
  24. data/examples/revealjs-plugins/chalkboard/img/whiteboard.png +0 -0
  25. data/examples/revealjs-plugins/reveal.js-menu/CONTRIBUTING.md +9 -0
  26. data/examples/revealjs-plugins/reveal.js-menu/LICENSE +19 -0
  27. data/examples/revealjs-plugins/reveal.js-menu/README.md +334 -0
  28. data/examples/revealjs-plugins/reveal.js-menu/bower.json +21 -0
  29. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/LICENSE.txt +34 -0
  30. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/all.css +5 -0
  31. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/brands.css +5 -0
  32. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/fontawesome.css +5 -0
  33. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/regular.css +5 -0
  34. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/solid.css +5 -0
  35. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/svg-with-js.css +5 -0
  36. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/v4-shims.css +2170 -0
  37. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/css/v4-shims.min.css +5 -0
  38. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-brands-400.eot +0 -0
  39. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-brands-400.svg +1127 -0
  40. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-brands-400.ttf +0 -0
  41. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-brands-400.woff +0 -0
  42. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-brands-400.woff2 +0 -0
  43. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-regular-400.eot +0 -0
  44. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-regular-400.svg +467 -0
  45. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-regular-400.ttf +0 -0
  46. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-regular-400.woff +0 -0
  47. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-regular-400.woff2 +0 -0
  48. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-solid-900.eot +0 -0
  49. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-solid-900.svg +2231 -0
  50. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-solid-900.ttf +0 -0
  51. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-solid-900.woff +0 -0
  52. data/examples/revealjs-plugins/reveal.js-menu/font-awesome/webfonts/fa-solid-900.woff2 +0 -0
  53. data/examples/revealjs-plugins/reveal.js-menu/menu.css +345 -0
  54. data/examples/revealjs-plugins/reveal.js-menu/menu.js +949 -0
  55. data/examples/revealjs-plugins/reveal.js-menu/package.json +22 -0
  56. data/examples/slide-numbers-custom.adoc +18 -0
  57. data/examples/slide-numbers-for-speaker.adoc +23 -0
  58. data/examples/slide-numbers-no.adoc +18 -0
  59. data/examples/slide-numbers.adoc +28 -0
  60. data/examples/source-callouts.adoc +11 -1
  61. data/examples/source-highlightjs.adoc +9 -0
  62. data/examples/speaker-notes.adoc +25 -2
  63. data/lib/asciidoctor-revealjs.rb +1 -0
  64. data/lib/asciidoctor-revealjs/converter.rb +655 -542
  65. data/lib/asciidoctor-revealjs/version.rb +1 -1
  66. data/templates/admonition.html.slim +2 -3
  67. data/templates/asciidoctor_revealjs.css.slim +14 -0
  68. data/templates/document.html.slim +69 -26
  69. data/templates/helpers.rb +23 -0
  70. data/templates/listing.html.slim +35 -35
  71. data/templates/notes.html.slim +1 -0
  72. data/templates/open.html.slim +7 -4
  73. data/templates/section.html.slim +2 -8
  74. data/templates/sidebar.html.slim +8 -5
  75. data/templates/toc.html.slim +2 -2
  76. metadata +81 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: fb3a1b6a31f4e569aedb317d4336379cc0e0d06213af3d7ea7034b711e55527d
4
- data.tar.gz: f11fceb6fced6938a57743f9a0e80da396df93c1e19ad10a53b0ace34a6e2cda
3
+ metadata.gz: 92c4880c5ceb7627a9f3aecb18cdc51e2decb5aeda93ae43acc0f2dba469c166
4
+ data.tar.gz: bf5d778618042ed402c2ae33c3de5c1601c47534db1ef126123a2781b9d51c3a
5
5
  SHA512:
6
- metadata.gz: ea7418e3d9129555f0f99b6bb3180eaf0ffb60ad9f225453a03e4c1b16956fbdfdaf21171abbdeacca1082db679bc9e2fe6d7c094741f140e93fb8e6edf8835d
7
- data.tar.gz: 663b7b4a04609b03d1ff797ebee604009c37f20a315dd4afbc7756c49bc6b786e21938c402fa02dcca0fc8b04f7c6b15ab05e7d1870930385017458b62582742
6
+ metadata.gz: 47aebfa9caca7b8ae9d623652f49cbee2b9dafdd9dbaf3dbb8ab4c09fce5fd8564660b5c16bf013a4cd8085e711087a27986929ce80b3444518ba4c492031d64
7
+ data.tar.gz: 03506ef9bc2d53d22f8a80ff924e561d32cb2b86634a5f6e892ffb9f15d2d8dbc6388b76e7492fc740f23c8376d8a8eae5a4a7db187394919655a974b37ebd2d
@@ -6,6 +6,78 @@
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
+ == 2.0.0 (2019-02-28)
10
+
11
+ Upgrade considerations::
12
+ * Node.js API change!
13
+ If you generate your reveal.js presentations using the node/javascript toolchain, you need to change how the {project-name} back-end is registered to Asciidoctor.js.
14
+ Instead of `require('asciidoctor-reveal.js')` you need to do:
15
+
16
+ var asciidoctorRevealjs = require('asciidoctor-reveal.js');
17
+ asciidoctorRevealjs.register()
18
+ +
19
+ This change enables new use cases like embedding a presentation in a React web app.
20
+
21
+ * Anchor links generated by {project-name} will change from now on when revealjs_history is set to true (default is false).
22
+ This is the consequence of upstream fixing a long standing issue (see https://github.com/hakimel/reveal.js/pull/1230[#1230] and https://github.com/hakimel/reveal.js/pull/2037[#2037]) and us removing a workaround (see {uri-issue}232[#232]).
23
+ Explicit anchors are not affected.
24
+ * Custom CSS might require adjustments.
25
+ Source and listing block are less deeply nested into `div` blocks now.
26
+ See {uri-issue}195[#195] and {uri-issue}223[#223].
27
+ * The reveal.js `marked` and `markdown` plugins are disabled by default now.
28
+ It is unlikely that they could have been used anyway.
29
+ See {uri-issue}204[#204].
30
+ * Dropped the ability to override the Reveal.JS theme and transitions dynamically with the URL query.
31
+ Was not compatible with Reveal.JS 3.x series released 4 years ago.
32
+
33
+ Enhancements::
34
+ * Easier speaker notes: a `.notes` role that apply to many AsciiDoc blocks (open, sidebar and admonition) ({uri-issue}202[#202])
35
+ * Added a role `right` that would apply a `float: right` to any block where it would be assigned ({uri-issue}197[#197], {uri-issue}213[#213], {uri-issue}215[#215])
36
+ * Allow the background color of slides to be set using CSS ({uri-issue}16[#16], {uri-issue}220[#220], {uri-issue}226[#226], {uri-issue}229[#229])
37
+ * Reveal.js's fragmentInURL option now supported ({uri-issue}206[#206], {uri-issue}214[#214])
38
+ * Documentation improvements ({uri-issue}141[#141], {uri-issue}182[#182], {uri-issue}190[#190], {uri-issue}203[#203], {uri-issue}215[#215], {uri-issue}216[#216], {uri-issue}222[#222])
39
+ * Support for Asciidoctor.js 1.5.6 and build simplification ({uri-issue}189[#189], {uri-issue}217[#217])
40
+ * Support to specify and use reveal.js plugins without modifying {project-name}'s source code ({uri-issue}196[#196], {uri-issue}118[#118], {uri-issue}201[#201], {uri-issue}204[#204])
41
+ * Node / Javascript back-end is now loaded on-demand with the `register()` method.
42
+ This allows embedding {project-name} into React or any other modern Javascript environment.
43
+ ({uri-issue}205[#205], {uri-issue}218[#218], {uri-issue}219[#219])
44
+ * `revealjsdir` attribute is set to a more sensible default when running under Node.js ({uri-issue}191[#191], {uri-issue}228[#228])
45
+ * Node / Javascript back-end updated to use Asciidoctor.js 1.5.9.
46
+ This extension is built with Opal 0.11.99.dev (6703d8d) in order to be compatible.
47
+ ({uri-issue}227[#227], {uri-issue}240[#240])
48
+
49
+ Compliance::
50
+ * AsciiDoc source callout icons now work ({uri-issue}54[#54], {uri-issue}168[#168], {uri-issue}224[#224])
51
+ * New reveal.js 3.7.0 features supported: `controlsTutorial`, `controlsLayout`, `controlsBackArrows`, new `slideNumber` formats, `showSlideNumber`, `autoSlideMethod`, `parallaxBackgroundHorizontal`, `parallaxBackgroundVertical` and `display` configuration parameters are now supported ({uri-issue}212[#212], {uri-issue}239[#239], TODO)
52
+ * Asciidoctor 2.0 ready ({uri-issue}245[#245])
53
+
54
+ Bug Fixes::
55
+ * Reveal.js' `stretch` class now works with listing blocks ({uri-issue}195[#195], {uri-issue}223[#223])
56
+ * Auto-generated slide IDs with unallowed characters (for revealjs history) now work properly.
57
+ Upstream reveal.js fixed a bug in 3.7.0 (https://github.com/hakimel/reveal.js/pull/2037[#2037]) and we removed our broken workaround.
58
+ ({uri-issue}192[#192], {uri-issue}232[#232])
59
+
60
+ Infrastructure::
61
+ * Travis testing prepared for upcoming Asciidoctor 2.0 ({uri-issue}216[#216])
62
+ * Travis testing for Ruby 2.6 ({uri-issue}243[#243])
63
+
64
+ === Release meta
65
+
66
+ * Released on: 2018-02-28
67
+ * Released by: Olivier Bilodeau
68
+ * Release beer: President's Choice Blonde Brew De-alcoholized Beer
69
+
70
+ {uri-repo}/releases/tag/v2.0.0[git tag] |
71
+ {uri-repo}/compare/v1.1.3...v2.0.0[full diff] |
72
+ {uri-repo}/milestone/6[milestone]
73
+
74
+ === Credits
75
+
76
+ Thanks to the following people who contributed to this release:
77
+
78
+ a4z, Dan Allen, Guillaume Grossetie, Harald, Jakub Jirutka, Olivier Bilodeau, stevewillson, Vivien Didelot
79
+
80
+
9
81
  == 1.1.3 (2018-01-31)
10
82
 
11
83
  A repackage of 1.1.2 with a fix for Ruby 2.5 environments
data/Gemfile CHANGED
@@ -2,3 +2,5 @@ source 'https://rubygems.org'
2
2
 
3
3
  # Specify your gem's dependencies in asciidoctor-revealjs.gemspec
4
4
  gemspec
5
+ # Asciidoctor.js 1.5.9 requires an unreleased Opal 0.11.99.dev (6703d8d)
6
+ gem 'opal', :git => 'https://github.com/opal/opal.git', :ref => '6703d8d'
@@ -4,6 +4,21 @@
4
4
 
5
5
  Short instructions that aim to help potential contributors.
6
6
 
7
+ == Getting Started
8
+
9
+ * Setup the Asciidoctor-revealjs plugin in <<ruby-localversion,development mode>>
10
+ * Modify the http://slim-lang.com/[slim templates] in `templates/`
11
+ * Templates need to be compiled before being used, do so with:
12
+
13
+ bundle exec rake build
14
+
15
+ * Then using the following command will render slides with your template changes baked in:
16
+
17
+ bundle exec asciidoctor-revealjs <source.adoc>
18
+
19
+ The next section will provide further help on how to use `print` statements or a debugger to assist development.
20
+
21
+
7
22
  == Inspect the template system
8
23
 
9
24
  To understand what you have access to in templates you can inject some ruby.
@@ -124,22 +139,22 @@ done with `bundler`:
124
139
  bundle --path=.bundle/gems --binstubs=.bundle/.bin
125
140
  bundle exec rake build
126
141
 
127
- Go to `test/output/slim/` folder and install `reveal.js`:
142
+ Go to `test/doctest` folder and install `reveal.js`:
128
143
 
129
- cd test/output/slim/
144
+ cd test/doctest/
130
145
  git clone https://github.com/hakimel/reveal.js.git
131
146
 
132
147
  === Render tests into .html
133
148
 
134
149
  From the project's root directory:
135
150
 
136
- bundle exec rake generate FORCE=yes
151
+ bundle exec rake doctest::generate FORCE=yes
137
152
 
138
153
  === Open rendered files
139
154
 
140
155
  NOTE: Right now, https://github.com/asciidoctor/asciidoctor-doctest/issues/12[doctest issue #12] means that the generated examples will not be pretty.
141
156
 
142
- You can open the generated `.html` in `test/output/slim/` in a Web browser.
157
+ You can open the generated `.html` in `test/doctest/` in a Web browser.
143
158
 
144
159
 
145
160
  == Asciidoctor API's gotchas
@@ -211,8 +226,7 @@ Makes triaging easier.
211
226
 
212
227
  In order to test the Node package, you first need to build the converter into Javascript and create a tarball of the project.
213
228
 
214
- $ bundle exec rake build:converter:opal
215
- $ npm run build
229
+ $ bundle exec rake build:js
216
230
  $ npm pack
217
231
 
218
232
  That last command will produce a file named `asciidoctor-reveal.js-<version>.tgz` in the working directory.
@@ -232,14 +246,15 @@ Then proceed as documented in the `README.adoc`.
232
246
 
233
247
  === Upgrade Asciidoctor.js version
234
248
 
235
- WARNING: It is important to track `Asciidoctor.js` and `bestikk-opal-compiler` versions together.
236
- The `opal-compiler` used to compile our node package must match `asciidoctor.js` `opal-runtime`.
237
- The former is explicitly installed by users on install and the later is specified in our `package.json`.
249
+ WARNING: It is important to track `Asciidoctor.js` and `opal` versions together.
250
+ The `opal` used to compile our node package must match `asciidoctor.js`'s `opal` requirement.
251
+ The former is specified in our `package.json` and the latter in the `asciidoctor-revealjs.gemspec`.
238
252
  When you update one remember to update the other.
239
- Versions known to work together can be found here, just replace <tag> with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/blob/<tag>/package.json
253
+ Versions known to work together can be found by looking at the Asciidoctor.js release notes, just replace <tag> with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/releases/tag/<tag>.
240
254
 
241
255
  == RubyGem package
242
256
 
257
+ [[ruby-localversion]]
243
258
  === Test a local asciidoctor-revealjs version
244
259
 
245
260
  Compile the converter:
@@ -278,13 +293,13 @@ Then run:
278
293
  $ gem push asciidoctor-revealjs-X.Y.Z.gem
279
294
 
280
295
  . Check that the new version is available on https://rubygems.org/gems/asciidoctor-revealjs[rubygems.org]
281
- . Generate a compatible version of the Ruby converter (using opal mode)
296
+ . Generate the javascript version of the Ruby converter
282
297
  +
283
- $ bundle exec rake build:converter:opal
298
+ $ bundle exec rake build:js
284
299
 
285
- . Build the node package (make sure you have `devDependencies` installed with: `npm install`):
300
+ . Test the node package (make sure you have `devDependencies` installed with: `npm install`):
286
301
  +
287
- $ npm run build
302
+ $ npm run test
288
303
 
289
304
  . Publish the node package on npm:
290
305
  +
@@ -1,6 +1,6 @@
1
1
  .The MIT License
2
2
  ....
3
- Copyright (C) 2012-2018 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project
3
+ Copyright (C) 2012-2019 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -40,8 +40,10 @@ There are two main technology stacks that can transform AsciiDoc into HTML5 / re
40
40
  Right now the Asciidoctor / Ruby stack is the better tested one but with the changes in v1.1.0 they have feature parity.
41
41
 
42
42
  ifeval::['{branch}' == 'master']
43
- NOTE: You're viewing the documentation for the upcoming release.
44
- If you're looking for the documentation for an older release, please refer to one of the following branches: +
43
+ NOTE: You're viewing the documentation for an upcoming release.
44
+ If you're looking for the documentation for the current release or an older one, please click on the appropriate link below: +
45
+ {uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest release)
46
+ &hybull;
45
47
  {uri-project-repo}/tree/maint-1.0.x#readme[1.0.x]
46
48
  &hybull;
47
49
  {uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with RevealJS 2.x)
@@ -101,7 +103,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
101
103
  . Optional: Copy or clone reveal.js presentation framework.
102
104
  Allows you to modify themes or view slides offline.
103
105
 
104
- $ git clone -b 3.6.0 --depth 1 https://github.com/hakimel/reveal.js.git
106
+ $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git
105
107
 
106
108
 
107
109
  === Rendering the AsciiDoc into slides
@@ -112,7 +114,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
112
114
  . Generate HTML presentation from the AsciiDoc source
113
115
 
114
116
  $ bundle exec asciidoctor-revealjs \
115
- -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.6.0 CONTENT_FILE.adoc
117
+ -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 CONTENT_FILE.adoc
116
118
 
117
119
  . If you did the optional step of having a local reveal.js clone you can
118
120
  convert AsciiDoc source with
@@ -132,6 +134,9 @@ First you must install and configure {uri-nodejs-download}[Node.js] on your mach
132
134
 
133
135
  Using npm:
134
136
 
137
+ Create a directory to place slides. Initialize the directory to store npm packages within that directory.
138
+
139
+ $ echo {} > package.json # eliminates warnings, use `npm init` if you prefer
135
140
  $ npm i --save asciidoctor-reveal.js
136
141
 
137
142
  === Rendering the AsciiDoc into slides
@@ -144,11 +149,11 @@ Here we are converting a file named `presentation.adoc` into a reveal.js present
144
149
  ----
145
150
  // Load asciidoctor.js and asciidoctor-reveal.js
146
151
  var asciidoctor = require('asciidoctor.js')();
147
- require('asciidoctor-reveal.js');
152
+ var asciidoctorRevealjs = require('asciidoctor-reveal.js');
153
+ asciidoctorRevealjs.register()
148
154
 
149
155
  // Convert the document 'presentation.adoc' using the reveal.js converter
150
- var attributes = {'revealjsdir': 'node_modules/reveal.js@'};
151
- var options = {safe: 'safe', backend: 'revealjs', attributes: attributes};
156
+ var options = {safe: 'safe', backend: 'revealjs'};
152
157
  asciidoctor.convertFile('presentation.adoc', options); // <1>
153
158
  ----
154
159
  <1> Creates a file named `presentation.html` (in the directory where command is run)
@@ -157,9 +162,6 @@ asciidoctor.convertFile('presentation.adoc', options); // <1>
157
162
  [source, asciidoc]
158
163
  ----
159
164
  = Title Slide
160
- // depending on your npm version, you might need to override the default
161
- // 'revealjsdir' value by removing the comments from the line below:
162
- //:revealjsdir: node_modules/asciidoctor-reveal.js/node_modules/reveal.js
163
165
 
164
166
  == Slide One
165
167
 
@@ -195,15 +197,17 @@ Additional examples can be found in the AsciiDoc files (.adoc) in `examples/`.
195
197
 
196
198
  == Slide Two
197
199
 
198
- Hello World - Good Bye Cruel World
200
+ A Great Story
199
201
 
200
- [NOTE.speaker]
202
+ [.notes]
201
203
  --
202
- Actually things aren't that bad
204
+ * tell anecdote
205
+ * make a point
203
206
  --
204
207
  ----
205
208
 
206
209
  In previous snippet we are creating a slide titled Slide One with bullets and another one titled Slide Two with centered text (reveal.js`' default behavior) with {uri-revealjs-gh}#speaker-notes[speaker notes].
210
+ Other syntax exists to create speaker notes, see `examples/speaker-notes.adoc`.
207
211
 
208
212
  Starting with Reveal.js 3.5 speaker notes supports configurable layouts:
209
213
  image:https://cloud.githubusercontent.com/assets/629429/21808439/b941eb52-d743-11e6-9936-44ef80c60580.gif[]
@@ -215,8 +219,7 @@ You can get a Web server running quickly with:
215
219
 
216
220
  ruby -run -e httpd . -p 5000 -b 127.0.0.1
217
221
 
218
- Then open your browser at: http://localhost:5000/
219
-
222
+ Then use your browser to navigate to the URL \http://localhost:5000.
220
223
 
221
224
  === Slides without titles
222
225
 
@@ -241,8 +244,46 @@ endif::[]
241
244
 
242
245
  NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to.
243
246
 
247
+ IMPORTANT: Like the first page of an AsciiDoc document, the first slide is handled differently.
248
+ To hide the whole slide use the `:notitle:` http://asciidoctor.org/docs/user-manual/#header-summary[document attribute].
249
+ To achieve the effect of hiding only the first slide's title, combine the `:notitle:` attribute on the first slide and use `[%notitle]` on the second slide which will, in effect, be your first slide now.
250
+
251
+
252
+ === Background Colors
253
+
254
+ Background colors for slides can be specified by two means: a classic one and one using AsciiDoc roles.
255
+ See <<examples/background-color.adoc#,background-color.adoc>> for more examples.
256
+
257
+ ==== Using AsciiDoc Roles
258
+
259
+ Using roles respects the AsciiDoc philosophy of separation of content and presentation.
260
+ Colors are to be defined by CSS and the <<customcss,`:customcss:` attribute>> need to be used to specify the CSS file to load.
261
+ To avoid clashing with existing reveal.js themes or CSS, a specific CSS class called `background` is expected to be present.
262
+ Here is an example:
263
+
264
+
265
+ [source, asciidoc]
266
+ ----
267
+ = Title
268
+ :customcss: my-css.css
269
+
270
+ [.red.background]
271
+ == Slide One
272
+
273
+ Is very red
274
+ ----
275
+
276
+ .my-css.css
277
+ [source, css]
278
+ ----
279
+ section.red.background {
280
+ background-color: red;
281
+ }
282
+ ----
283
+
284
+ NOTE: The `canvas` keyword can be used instead of `background` for the same effect.
244
285
 
245
- === Background colors
286
+ ==== Classic
246
287
 
247
288
  [source, asciidoc]
248
289
  ----
@@ -271,7 +312,7 @@ It sets reveal.js`' `data-background-image` attribute.
271
312
  The `size` attribute is also supported.
272
313
  See the {uri-revealjs-gh}#image-backgrounds[relevant reveal.js documentation] for details.
273
314
 
274
- NOTE: Background images file names are now relative to the `:imagedir:` attribute if set.
315
+ NOTE: Background images file names are now relative to the `:imagesdir:` attribute if set.
275
316
 
276
317
  NOTE: The `canvas` keyword can be used instead of `background` for the same effect.
277
318
 
@@ -460,6 +501,40 @@ Here is {uri-revealjs-gh}#markup[the relevant reveal.js
460
501
  documentation] on that topic.
461
502
 
462
503
 
504
+ === Asciidoctor-reveal.js specific roles
505
+
506
+ 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:
507
+
508
+ [source, asciidoc]
509
+ ....
510
+ [.important-text]
511
+ == Slide Title
512
+
513
+ * Some
514
+ * Information
515
+ ....
516
+
517
+ Or
518
+
519
+ [source, asciidoc]
520
+ ....
521
+ [role="important-text"]
522
+ == Slide Title
523
+
524
+ * Some
525
+ * Information
526
+ ....
527
+
528
+ See https://asciidoctor.org/docs/user-manual/#role[Asciidoctor's documentation] for more details.
529
+
530
+ .Image specific note
531
+ In addition to the https://asciidoctor.org/docs/user-manual/\#positioning-attributes[existing attributes] to position images, roles can be used as well. However, the shorthand syntax (.) doesn't work in the image macro arguments but must be used above with the angle bracket syntax.
532
+ See <<examples/images.adoc#,images.adoc>> for examples.
533
+
534
+ Here is a list of supported roles:
535
+
536
+ right:: Will apply a `float: right` style to the affected block
537
+
463
538
 
464
539
  === Title slide customization
465
540
 
@@ -527,6 +602,7 @@ Detailed view diagram
527
602
  ----
528
603
 
529
604
 
605
+ [[customcss]]
530
606
  === CSS override
531
607
 
532
608
  If you use the `:customcss:` document attribute, a CSS file of the name given in the attribute is added to the list of CSS resources loaded by the rendered HTML.
@@ -624,19 +700,47 @@ Default is built-in [path]_lib/css/zenburn.css_.
624
700
  |<file\|URL>
625
701
  |Overrides reveal.js directory.
626
702
  Example: ../reveal.js or
627
- https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0
703
+ https://cdnjs.com/libraries/reveal.js/3.7.0[https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0].
704
+ Default is `reveal.js/` unless in a Node.js environment where it is `node_modules/reveal.js/`.
628
705
 
629
706
  |:revealjs_controls:
630
707
  |*true*, false
631
- |Display controls in the bottom right corner.
708
+ |Display presentation control arrows
709
+
710
+ |:revealjs_controlsTutorial:
711
+ |*true*, false
712
+ |Help the user learn the controls by providing hints, for example by bouncing the down arrow when they first encounter a vertical slide
713
+
714
+ |:revealjs_controlsLayout:
715
+ |edges, *bottom-right*
716
+ |Determines where controls appear, "edges" or "bottom-right"
717
+
718
+ |:revealjs_controlsBackArrows:
719
+ |*faded*, hidden, visible
720
+ |Visibility rule for backwards navigation arrows; "faded", "hidden" or "visible"
632
721
 
633
722
  |:revealjs_progress:
634
723
  |*true*, false
635
724
  |Display a presentation progress bar.
636
725
 
637
726
  |:revealjs_slideNumber:
638
- |true, *false*
639
- |Display the page number of the current slide.
727
+ |true, *false*, h.v, h/v, c, c/t
728
+ a|Display the page number of the current slide.
729
+ *true* will display the slide number with default formatting.
730
+ Additional formatting is available:
731
+
732
+ h.v:: horizontal . vertical slide number (default)
733
+ h/v:: horizontal / vertical slide number
734
+ c:: flattened slide number
735
+ c/t:: flattened slide number / total slides
736
+
737
+ |:revealjs_showSlideNumber:
738
+ |*all*, speaker, print
739
+ a|Control which views the slide number displays on using the "showSlideNumber" value:
740
+
741
+ all:: show on all views (default)
742
+ speaker:: only show slide numbers on speaker notes view
743
+ print:: only show slide numbers when printing to PDF
640
744
 
641
745
  |:revealjs_history:
642
746
  |true, *false*
@@ -670,10 +774,30 @@ https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0
670
774
  |*true*, false
671
775
  |Turns fragments on and off globally.
672
776
 
777
+ |:revealjs_fragmentInURL:
778
+ |true, *false*
779
+ |Flags whether to include the current fragment in the URL, so that reloading brings you to the same fragment position
780
+
673
781
  |:revealjs_embedded:
674
782
  |true, *false*
675
783
  |Flags if the presentation is running in an embedded mode (i.e., contained within a limited portion of the screen).
676
784
 
785
+ |:revealjs_help:
786
+ |*true*, false
787
+ |Flags if we should show a help overlay when the questionmark key is pressed
788
+
789
+ |:revealjs_showNotes:
790
+ |*true*, false
791
+ |Flags if speaker notes should be visible to all viewers
792
+
793
+ |:revealjs_autoPlayMedia:
794
+ |*null*, true, false
795
+ a|Global override for autolaying embedded media (video/audio/iframe)
796
+
797
+ null:: Media will only autoplay if data-autoplay is present
798
+ true:: All media will autoplay, regardless of individual setting
799
+ false:: No media will autoplay, regardless of individual setting
800
+
677
801
  |:revealjs_autoSlide:
678
802
  |<integer>
679
803
  |Delay in milliseconds between automatically proceeding to the next slide.
@@ -684,6 +808,16 @@ This value can be overwritten by using a `data-autoslide` attribute on your slid
684
808
  |*true*, false
685
809
  |Stop auto-sliding after user input.
686
810
 
811
+ |:revealjs_autoSlideMethod:
812
+ |*Reveal.navigateNext*
813
+ |Use this method for navigation when auto-sliding
814
+
815
+ |:revealjs_defaultTiming:
816
+ |<integer>
817
+ |Specify the average time in seconds that you think you will spend presenting each slide.
818
+ This is used to show a pacing timer in the speaker view.
819
+ Defaults to *120*
820
+
687
821
  |:revealjs_mouseWheel:
688
822
  |true, *false*
689
823
  |Enable slide navigation via mouse wheel.
@@ -695,6 +829,7 @@ This value can be overwritten by using a `data-autoslide` attribute on your slid
695
829
  |:revealjs_previewLinks:
696
830
  |true, *false*
697
831
  |Opens links in an iframe preview overlay.
832
+ Add `data-preview-link` and `data-preview-link="false"` to customise each link individually
698
833
 
699
834
  |:revealjs_transition:
700
835
  |none, fade, *slide*, convex, concave, zoom
@@ -721,6 +856,25 @@ Defaults to none
721
856
  |<CSS size syntax>
722
857
  |Parallax background size (accepts any CSS syntax).
723
858
  Defaults to none
859
+
860
+ |:revealjs_parallaxBackgroundHorizontal:
861
+ |<Number of pixels>
862
+ a|Number of pixels to move the parallax background per slide
863
+
864
+ - Calculated automatically unless specified
865
+ - Set to 0 to disable movement along an axis
866
+
867
+ |:revealjs_parallaxBackgroundVertical:
868
+ |<Number of pixels>
869
+ a|Number of pixels to move the parallax background per slide
870
+
871
+ - Calculated automatically unless specified
872
+ - Set to 0 to disable movement along an axis
873
+
874
+ |:revealjs_display:
875
+ |<a valid CSS display mode>
876
+ |The display mode that will be used to show slides.
877
+ Defaults to *block*
724
878
  |===
725
879
 
726
880
  If you want to build a custom theme or customize an existing one you should
@@ -729,13 +883,75 @@ look at the
729
883
  theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to
730
884
  activate it.
731
885
 
886
+ === Default plugins
887
+
888
+ By default, generated presentations will have the following reveal.js plugins enabled:
889
+
890
+ * plugin/zoom-js/zoom.js
891
+ * plugin/notes/notes.js
892
+
893
+ All these plugins are part of the reveal.js distribution.
894
+
895
+ To enable or disable a built-in plugin, it is possible to set the `revealjs_plugin_[plugin name]` attribute to `enable` or `disable`.
896
+
897
+ For example, to disable all the default plugins set the following document attributes:
898
+
899
+ ----
900
+ :revealjs_plugin_zoom: disabled
901
+ :revealjs_plugin_notes: disabled
902
+ ----
903
+
904
+ reveal.js ships with a plugin that allows to create a PDF from a slide deck.
905
+ To enable this plugin, set the `revealjs_plugin_pdf` attribute.
906
+
907
+ ----
908
+ :revealjs_plugin_pdf: enabled
909
+ ----
910
+
911
+ 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.
912
+
913
+ TIP: To work properly, this plugin requires a Chrome-based browser.
914
+
915
+
916
+ === Additional plugins
917
+
918
+ Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files.
919
+
920
+ . Extract the plugin files in a directory
921
+ . Create a Javascript file that will contain the Javascript statements to load the plugin (only one required even if you are using several plugins)
922
+ . Add a `:revealjs_plugins:` attribute to point to that Javascript file
923
+ . (Optional) Add a `:revealjs_plugins_configuration:` attribute to point to a Javascript file that configures the plugins you use
924
+
925
+ Looking at the example provided in the repository will provide guidance: link:examples/revealjs-plugins.adoc[AsciiDoc source], link:examples/revealjs-plugins.js[Plugin Loader], link:examples/revealjs-plugins-conf.js[Plugin Configuration].
926
+
927
+ Read {uri-revealjs-gh}#dependencies[the relevant reveal.js documentation] to understand more about reveal.js plugins.
928
+ A {uri-revealjs-gh}/wiki/Plugins,-Tools-and-Hardware[list of existing reveal.js plugins] is also maintained upstream.
929
+
930
+
732
931
  == Minimum Requirements
733
932
 
734
- * asciidoctor 1.5.6
933
+ Our requirements are expressed in our packages and by our dependencies.
934
+ Basically, all you need is the package manager of the flavor of Asciidoctor-Reveal.js you are interested to run:
935
+
936
+ * With Ruby / Bundler: A https://www.ruby-lang.org/en/downloads/[recent Ruby] and https://bundler.io/[Bundler]
937
+ * With Javascript (Node.js) / NPM: a https://nodejs.org/en/download/[recent Node.js] environment
938
+
939
+ If you need more details about our dependencies check out Asciidoctor dependencies:
940
+
941
+ * With Ruby / Bundler: https://asciidoctor.org/#requirements[Asciidoctor] 1.5.6
942
+ * With Javascript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v1.5.6/package.json[Asciidoctor.js] 1.5.6
943
+
944
+
945
+ == Contributing
946
+
947
+ Interested in contributing?
948
+ We are interested!
949
+ Developer-focused documentation is link:HACKING.adoc[over here].
950
+
735
951
 
736
952
  == Copyright and Licensing
737
953
 
738
- Copyright (C) 2012-2018 {authors} and the Asciidoctor Project.
954
+ Copyright (C) 2012-2019 {authors} and the Asciidoctor Project.
739
955
  Free use of this software is granted under the terms of the MIT License.
740
956
 
741
957
  ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]