tag. Anything accepted by CSS color formats works. === Background images [source, asciidoc] ---- [%notitle] == Grand Announcement image::cover.jpg[background, size=cover] ---- This will put `cover.jpg` as the slide's background image. It sets reveal.js`' `data-background-image` attribute. The `size` attribute is also supported. See the {uri-revealjs-gh}#image-backgrounds[relevant reveal.js documentation] for details. NOTE: Background images file names are now relative to the `:imagesdir:` attribute if set. NOTE: The `canvas` keyword can be used instead of `background` for the same effect. [source, asciidoc] ---- [%notitle] == The Great Goat image::https://upload.wikimedia.org/wikipedia/commons/b/b2/Hausziege_04.jpg[canvas,size=contain] ---- As you can see, you can use a URL to specify your image resource too. [#background_videos] === Background videos A background video for a slide can be specified using the `background-video` element attribute. [source, asciidoc] ---- [background-video="https://my.video/file.mp4",background-video-loop=true,background-video-muted=true] == Nice background! ---- For convenience `background-video-loop` and `background-video-muted` attributes are mapped to `loop` and `muted` options which can be specified with `options="loop,muted"`. For example: [source, asciidoc] ---- [background-video="https://my.video/file.mp4",options="loop,muted"] == Nice background! ---- See {uri-revealjs-gh}#video-backgrounds[the relevant reveal.js documentation] for details. Note that the `data-` prefix is not required in asciidoc files. === Background iframes The background can be replaced with anything a browser can render in an iframe using the `background-iframe` reveal.js feature. [source, asciidoc] ---- [%notitle,background-iframe="https://www.youtube.com/embed/LaApqL4QjH8?rel=0&start=3&enablejsapi=1&autoplay=1&loop=1&controls=0&modestbranding=1"] == a youtube video ---- See {uri-revealjs-gh}#iframe-backgrounds[the relevant reveal.js documentation] for details. === Slide Transitions [source, asciidoc] ---- [transition=zoom, %notitle] == Zoom zoom This slide will override the presentation transition and zoom! [transition-speed=fast, %notitle] == Speed Choose from three transition speeds: default, fast or slow! ---- See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details. === Fragments [source, asciidoc] ---- == Slide Four [%step] * this * is * revealed * gradually ---- Slide Four has bullets that are revealed one after the other. This is what `reveal.js` calls http://lab.hakim.se/reveal-js/#/fragments[fragments]. Applying the step option or role on a list (`[%step]` or `[.step]`) will do the trick. Here is {uri-revealjs-gh}#fragments[the relevant reveal.js documentation] on the topic. Note that only `fade-in` is supported for lists at the moment. === Stretch class attribute Reveal.js supports a special class that will give all available screen space to an HTML node. This class element is named `stretch`. Sometimes it's desirable to have an element, like an image or video, stretch to consume as much space as possible within a given slide. To apply that class to block simply use asciidoctor's class assignment: [.stretch] See {uri-revealjs-gh}#stretching-elements[reveal.js documentation on stretching elements]. === Videos In addition to <>, videos can be inserted directly into slides. The syntax is the standard http://asciidoctor.org/docs/user-manual/#video[asciidoc video block macro] syntax. [source, asciidoc] ---- == Trains, we love trains! video::kZH9JtPBq7k[youtube, start=34, options=autoplay] ---- By default videos are given as much space as possible. 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 ---- [NOTE] ---- By default, we are using a prebuilt version of Highlight.js with 34 commonly used languages hosted on https://cdnjs.com/[cdnjs]. You can load additionnal languages using the `:highlightjs-languages:` attribute: ``` // load yaml and scilab languages :highlightjs-languages: yaml, scilab ``` You can also load Highlight.js from a custom base directory (or remote URL) using the `:highlightjsdir:` attribute: ``` // load from a local path :highlightjsdir: highlight // load from jsdelivr CDN //:highlightjsdir: https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.18.0/build ---- Once enabled, you can write code blocks as usual: [source, asciidoc] .... == Slide Five Uses highlighted code [source, python] ---- print "Hello World" ---- .... 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: [source, asciidoc] .... == Slide Five [source,perl] ---- print "$0: hello world\n" ---- .... [NOTE] Alternatively, you can use http://rouge.jneen.net/[Rouge], 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. === Vertical slides [source, asciidoc] .... == Slide Six Top slide === Slide Six.One This is a vertical subslide .... Slide Six uses the vertical slide feature of `reveal.js`. Slide Six.One will be rendered vertically below Slide Six. Here is {uri-revealjs-gh}#markup[the relevant reveal.js documentation] on that topic. === Columns layout Inspired by https://bulma.io/[Bulma], Asciidoctor reveal.js supports columns layout out-of-the-box: [source, asciidoc] .... [.columns] == 2 columns [.column] -- * **Edgar Allen Poe** * Sheri S. Tepper * Bill Bryson -- [.column] -- Edgar Allan Poe (/poʊ/; born Edgar Poe; January 19, 1809 – October 7, 1849) was an American writer, editor, and literary critic. -- .... If you do not specify a size, each column will have an equal width, no matter the number of columns. [source, asciidoc] .... [.columns] == 3 columns [.column] * Java * **Kotlin** [.column] * Node * **Deno** [.column] * Ruby * **Crystal** .... If you want to change the size of a single column, you can use one of the following classes: * `is-three-quarters` * `is-two-thirds` * `is-half` * `is-one-third` * `is-one-quarter` * `is-full` The other columns will fill up the remaining space automatically. + You can use the following multiples of 20% as well: * `is-four-fifths` * `is-three-fifths` * `is-two-fifths` * `is-one-fifth` [source, asciidoc] .... [.columns] == Columns with size [.column.is-one-third] -- * **Kotlin** * Java * Scala -- [.column] -- Programming language for Android, mobile cross-platform and web development, server-side, native, and data science. Open source forever Github. -- .... The vertical alignment of columns defaults to top aligned. Content can be centered by adding the `is-vcentered` class to the slide. [source, asciidoc] .... [.columns.is-vcentered] == Columns Vertically Centered [.column] -- * Few * Bullets * Here -- [.column] image::large-image.png[] .... === Asciidoctor reveal.js specific roles 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: [source, asciidoc] .... [.important-text] == Slide Title * Some * Information .... Or [source, asciidoc] .... [role="important-text"] == Slide Title * Some * Information .... See https://asciidoctor.org/docs/user-manual/#role[Asciidoctor's documentation] for more details. .Image specific note 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. See <> for examples. Here is a list of supported roles: right:: Will apply a `float: right` style to the affected block === Asciidoctor reveal.js specific attributes ==== iFrame Preview Overlay The reveal.js feature activated by a global `previewLinks: true` configuration or by adding the `data-preview-link` HTML attribute to `` tags can be activated by using special AsciiDoc attributes. On links use the `preview=true` attribute, on images use the `link_preview=true` attribute and globally you can set `:revealjs_previewlinks:` attribute. See <> and <> for examples. === Title slide customization The title slide is customized via Asciidoc attributes. These are the global variable assigned at the top of a document under the lead 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-`. ifeval::[{safe-mode-level} >= 20] See <>. endif::[] ifeval::[{safe-mode-level} < 20] Here is an example: .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. === Content meant for multiple converters Some content can be created with both slides and book in mind. To mark slides split points you can use preprocessor conditionals combined with a backend declaration. Breaking points are set using slides with no title `=== !` wrapped in a conditional: `ifdef::backend-revealjs[=== !]`. In the end, the whole document has to be compiled with the backend option: `-b revealjs` For example: [source, asciidoc] ---- == Main section === Sub Section Small + Multiline + intro . very . long . list . of . items \ifdef::backend-revealjs[=== !] Some overview diagram \ifdef::backend-revealjs[=== !] Detailed view diagram ---- [[customcss]] === CSS override 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. Doing so, you can then easily override specific elements of your theme per presentation. For example, to do proper position-independent text placement of a title slide with a specific background you can use: [source, css] ---- .reveal section.title h1 { margin-top: 2.3em; } .reveal section.title small { margin-top: 15.3em; font-weight: bold; color: white; } ---- If the `:customcss:` attribute value is empty then `asciidoctor-revealjs.css` is the CSS resource that the presentation is linked to. === Slide state Reveal.js supports a {uri-revealjs-gh}#slide-states[data-state] tag that can be added on slides which gets rendered into `

` tags. In AsciiDoc the `data-state` can be applied to a slide by adding a state attribute to a section like this: [source, asciidoc] ---- [state=topic] == Epic Topic ---- That state can be queried from JavaScript or used in CSS to apply further customization to your slide deck. For example, by combining this feature with the <> one, you can alter fonts for specific pages with this CSS: [source, css] ---- @import 'https://fonts.googleapis.com/css?family=Baloo+Bhai'; section[data-state="topic"] h2 { font-family: 'Baloo Bhai', cursive; font-size: 4em; } ---- === Admonitions Asciidoctor font-based http://asciidoctor.org/docs/user-manual/#admonition[admonitions] are supported. Make sure to add the following attribute to your document: [source, asciidoc] ---- :icons: font ---- Here is an example slide: [source, asciidoc] ---- == But first WARNING: This presentation is dangerous! ---- Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support. === Supplemental Content with Docinfo // Originally from https://github.com/asciidoctor/asciidoctor-bespoke#supplemental-content It's possible to inject supplemental content into the output document using http://asciidoctor.org/docs/user-manual/#docinfo-file[docinfo files]. This core feature of AsciiDoc has been adapted to work with the reveal.js converter. Currently, there are three insertion locations for docinfo content in a reveal.js document: head:: content is inserted after the last child of the `` element header:: content is inserted before the first child of the `

` element (before the slides) footer:: content is inserted after the last child of the `

` element (after the slides) The content you want to insert goes into a sibling file of the slide deck document with the following filename patterns: head:: `docinfo-revealjs.html` header:: `docinfo-header-revealjs.html` footer:: `docinfo-footer-revealjs.html` For example, let's say you want to embed a tweet into your slide deck. You might inject the shared embedding JavaScript using a footer docinfo file: .src/docinfo-footer-revealjs.html [source,html] ---- ---- You then need to set the following document attribute in the AsciiDoc header: ---- :docinfo: shared ---- 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. == Reveal.js Options Some attributes can be set at the top of the document that are specific to the `reveal.js` converter. They use the same name as in the `reveal.js` project except that they are prepended by `revealjs_` and case doesn't matter. They are applied in the link:templates/document.html.slim[document template]. NOTE: Default settings are based on `reveal.js` default settings. [cols="1m,1,2"] |=== |Attribute |Value(s) |Description |:revealjs_theme: |beige, *black*, league, night, serif, simple, sky, solarized, white |Chooses one of reveal.js`' {uri-revealjs-gh}#theming[built-in themes]. |:revealjs_customtheme: | |Overrides CSS with given file or URL. Default is disabled. |:highlightjs-theme: | |Overrides https://highlightjs.org[highlight.js] CSS style with given file or URL. Default is built-in [path]_lib/css/zenburn.css_. |:revealjsdir: | |Overrides reveal.js directory. Example: ../reveal.js or https://cdn.jsdelivr.net/npm/reveal.js@3.9.2. Default is `reveal.js/` unless in a Node.js environment where it is `node_modules/reveal.js/`. |:revealjs_controls: |*true*, false |Display presentation control arrows |:revealjs_controlsTutorial: |*true*, false |Help the user learn the controls by providing hints, for example by bouncing the down arrow when they first encounter a vertical slide |:revealjs_controlsLayout: |edges, *bottom-right* |Determines where controls appear, "edges" or "bottom-right" |:revealjs_controlsBackArrows: |*faded*, hidden, visible |Visibility rule for backwards navigation arrows; "faded", "hidden" or "visible" |:revealjs_progress: |*true*, false |Display a presentation progress bar. |:revealjs_slideNumber: |true, *false*, h.v, h/v, c, c/t a|Display the page number of the current slide. *true* will display the slide number with default formatting. Additional formatting is available: h.v:: horizontal . vertical slide number (default) h/v:: horizontal / vertical slide number c:: flattened slide number c/t:: flattened slide number / total slides |:revealjs_showSlideNumber: |*all*, speaker, print a|Control which views the slide number displays on using the "showSlideNumber" value: all:: show on all views (default) speaker:: only show slide numbers on speaker notes view print:: only show slide numbers when printing to PDF |:revealjs_hash: |true, *false* |Add the current slide number to the URL hash so that reloading the page/copying the URL will return you to the same slide |:revealjs_history: |true, *false* |Push each slide change to the browser history. Implies `hash: true` |:revealjs_keyboard: |*true*, false |Enable keyboard shortcuts for navigation. |:revealjs_overview: |*true*, false |Enable the slide overview mode. |:revealjs_touch: |*true*, false |Enables touch navigation on devices with touch input. |:revealjs_center: |*true*, false |Vertical centering of slides. |:revealjs_loop: |true, *false* |Loop the presentation. |:revealjs_rtl: |true, *false* |Change the presentation direction to be RTL. |:revealjs_navigationMode: |*default*, linear, grid |See https://github.com/hakimel/reveal.js/#navigation-mode for details |:revealjs_shuffle: |true, *false* |Randomizes the order of slides each time the presentation loads |:revealjs_fragments: |*true*, false |Turns fragments on and off globally. |:revealjs_fragmentInURL: |true, *false* |Flags whether to include the current fragment in the URL, so that reloading brings you to the same fragment position |:revealjs_embedded: |true, *false* |Flags if the presentation is running in an embedded mode (i.e., contained within a limited portion of the screen). |:revealjs_help: |*true*, false |Flags if we should show a help overlay when the questionmark key is pressed |:revealjs_showNotes: |*true*, false |Flags if speaker notes should be visible to all viewers |:revealjs_autoPlayMedia: |*null*, true, false a|Global override for autolaying embedded media (video/audio/iframe) null:: Media will only autoplay if data-autoplay is present true:: All media will autoplay, regardless of individual setting false:: No media will autoplay, regardless of individual setting |:revealjs_preloadIframes: |*null*, true, false a|Global override for preloading lazy-loaded iframes 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 true:: All iframes with `data-src` will be loaded when within the `viewDistance` false:: All iframes with `data-src` will be loaded only when visible |:revealjs_autoSlide: | |Delay in milliseconds between automatically proceeding to the next slide. Disabled when set to *0* (the default). This value can be overwritten by using a `data-autoslide` attribute on your slides. |:revealjs_autoSlideStoppable: |*true*, false |Stop auto-sliding after user input. |:revealjs_autoSlideMethod: |*Reveal.navigateNext* |Use this method for navigation when auto-sliding |:revealjs_defaultTiming: | |Specify the average time in seconds that you think you will spend presenting each slide. This is used to show a pacing timer in the speaker view. Defaults to *120* |:revealjs_totalTime: | |Specify the total time in seconds that is available to present. 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. Defaults to *0* |:revealjs_minimumTimePerSlide: | |Specify the minimum amount of time you want to allot to each slide, if using the totalTime calculation method. If the automated time allocation causes slide pacing to fall below this threshold, then you will see an alert in the speaker notes window. Defaults to *0*. |:revealjs_mouseWheel: |true, *false* |Enable slide navigation via mouse wheel. |:revealjs_hideInactiveCursor: |*true*, false |Hide cursor if inactive |:revealjs_hideCursorTime: | |Time before the cursor is hidden (in ms). Defaults to *5000*. |:revealjs_hideAddressBar: |*true*, false |Hides the address bar on mobile devices. |:revealjs_previewLinks: |true, *false* |Opens links in an iframe preview overlay. Add the `preview=true` attribute on links or `link_preview=true` attribute on images to customize each link individually. |:revealjs_transition: |none, fade, *slide*, convex, concave, zoom |Transition style. |:revealjs_transitionSpeed: |*default*, fast, slow |Transition speed. |:revealjs_backgroundTransition: |none, *fade*, slide, convex, concave, zoom |Transition style for full page slide backgrounds. |:revealjs_viewDistance: | |Number of slides away from the current that are visible. Default: *3*. |:revealjs_mobileViewDistance: | |Number of slides away from the current that are visible on mobile devices. It is advisable to set this to a lower number than viewDistance in order to save resources. Default *3*. |:revealjs_parallaxBackgroundImage: | |Parallax background image. Defaults to none |:revealjs_parallaxBackgroundSize: | |Parallax background size (accepts any CSS syntax). Defaults to none |:revealjs_parallaxBackgroundHorizontal: | a|Number of pixels to move the parallax background per slide - Calculated automatically unless specified - Set to 0 to disable movement along an axis |:revealjs_parallaxBackgroundVertical: | a|Number of pixels to move the parallax background per slide - Calculated automatically unless specified - Set to 0 to disable movement along an axis |:revealjs_display: | |The display mode that will be used to show slides. Defaults to *block* |:revealjs_width: | | Independent from the values, the aspect ratio will be preserved when scaled to fit different resolutions. Defaults to *960* |:revealjs_height: | | See `:revealjs_width:`. Defaults to *700* |:revealjs_margin: | | Factor of the display size that should remain empty around the content. Defaults to *0.1* |:revealjs_pdfseparatefragments: |*true*, false |In PDF export, put each fragment on a separate page. Defaults to *true* |:revealjs_pdfmaxpagesperslide: | |In PDF export, when a slide does not fit on a single page, maximum number of pages. Defaults to *1* |=== If you want to build a custom theme or customize an existing one you should look at the {uri-revealjs-gh}/blob/master/css/theme/README.md[reveal.js theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to activate it. === PDF Export Follow https://github.com/hakimel/reveal.js#pdf-export[reveal.js' documentation] for PDF export. We would add that we have successfully used PDF export without the requirement of a Web server. === Default plugins By default, generated presentations will have the following reveal.js plugins enabled: * plugin/zoom-js/zoom.js * plugin/notes/notes.js All these plugins are part of the reveal.js distribution. To enable or disable a built-in plugin, it is possible to set the `revealjs_plugin_[plugin name]` attribute to `enable` or `disable`. For example, to disable all the default plugins set the following document attributes: ---- :revealjs_plugin_zoom: disabled :revealjs_plugin_notes: disabled ---- === Additional plugins Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files. . Extract the plugin files in a directory . Create a JavaScript file that will contain the JavaScript statements to load the plugin (only one required even if you are using several plugins) . Add a `:revealjs_plugins:` attribute to point to that JavaScript file . (Optional) Add a `:revealjs_plugins_configuration:` attribute to point to a JavaScript file that configures the plugins you use 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]. Read {uri-revealjs-gh}#dependencies[the relevant reveal.js documentation] to understand more about reveal.js plugins. A {uri-revealjs-gh}/wiki/Plugins,-Tools-and-Hardware[list of existing reveal.js plugins] is also maintained upstream. == Minimum Requirements Our requirements are expressed in our packages and by our dependencies. Basically, all you need is the package manager of the flavor of Asciidoctor reveal.js you are interested to run: * With Ruby / Bundler: A https://www.ruby-lang.org/en/downloads/[recent Ruby] and https://bundler.io/[Bundler] * With JavaScript (Node.js) / npm: a https://nodejs.org/en/download/[recent Node.js] environment If you need more details about our dependencies check out Asciidoctor dependencies: * With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10 * With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3 [[revealjs-compatibility-matrix]] == reveal.js Compatibility Matrix We try as much as possible to be compatible with a broad range of reveal.js versions. However, changes made by that project sometimes forces us to drop compatibility with older reveal.js releases. This table tracks this compatibility. |=== |Asciidoctor reveal.js version |reveal.js version |4.x |3.9 - 3.8 |3.x, 2.x, 1.x |3.7 - 3.0 |Unversioned releases |2.x |=== [[asciidoctorjs-compatibility-matrix]] == Asciidoctor.js Compatibility Matrix NOTE: This section is intended only for more advanced users who combine extensions or maintain slide decks over many releases and need to update their dependencies. Due to our Ruby to JavaScript conversion process, published npm packages have strict requirements with which version of Asciidoctor.js they are compatible with. This table tracks this compatibility. |=== |Asciidoctor-reveal.js version |Asciidoctor.js version |3.x |2.x |2.x |1.5.9 |1.1.x |1.5.6-preview.4 |=== Be aware that it is always possible to recompile the converter into JavaScript from source so compatibility can be created by anyone if needed. More details on that topic can be found link:HACKING.adoc#node-binary-compatibility[in the development guide]. == Showcase Presentations === Power Catchup -- Everything Practical and Important in Java 9 to 13 A smooth presentation, featuring video backgrounds, slide transitions, code and callout examples and the use of notes. https://bentolor.github.io/java9to13/[Presentation] and https://github.com/bentolor/java9to13[source] ==== Screenshots image:{showcasedir}/java9to13_4.png[width=200,link=./{showcasedir}/java9to13_4.png] image:{showcasedir}/java9to13_1.jpg[width=200,link={showcasedir}/java9to13_1.jpg] image:{showcasedir}/java9to13_2.jpg[width=200,link={showcasedir}/java9to13_2.jpg] image:{showcasedir}/java9to13_3.png[width=200,link={showcasedir}/java9to13_3.png] == Contributing Interested in contributing? We are interested! Developer-focused documentation is link:HACKING.adoc[over here]. == Copyright and Licensing Copyright (C) 2012-2020 {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 <> file for details.]