README.adoc in asciidoctor-revealjs-3.1.0 vs README.adoc in asciidoctor-revealjs-4.0.0

- old
+ new

@@ -19,11 +19,11 @@ :uri-asciidoctor: https://github.com/asciidoctor/asciidoctor :uri-asciidoctorjs: https://github.com/asciidoctor/asciidoctor.js :uri-revealjs-home: http://lab.hakim.se/reveal-js/ :uri-revealjs-gh: https://github.com/hakimel/reveal.js :uri-nodejs-download: https://nodejs.org/en/download/ -:showcasedir: showcase +:showcasedir: showcase ifdef::env-github[] image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js] image:http://img.shields.io/gem/v/asciidoctor-revealjs.svg[gem, link=https://rubygems.org/gems/asciidoctor-revealjs] image:http://img.shields.io/npm/v/@asciidoctor/reveal.js.svg[npm, link=https://www.npmjs.org/package/@asciidoctor/reveal.js] @@ -32,21 +32,24 @@ // IMPORTANT: Changes made to this description should be sync'ed with the readme field in package.json. {uri-project-repo}[Asciidoctor reveal.js] is a converter for {uri-asciidoctor}[Asciidoctor] and {uri-asciidoctorjs}[Asciidoctor.js] that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the {uri-revealjs-home}[reveal.js] presentation framework. TIP: Want to see some example presentations, see <<Showcase Presentations>> -There are three main technology stacks that can transform AsciiDoc into HTML5 / reveal.js: +There are four main technology stacks that can convert AsciiDoc into HTML5 / reveal.js: * Asciidoctor / Ruby / Bundler (See <<Ruby Setup>>) * Asciidoctor.js / JavaScript (Node.js) / npm (See <<Node / JavaScript Setup>>) * Standalone Executable (See <<Standalone Executable>>) +* AsciidoctorJ / JVM / Maven (See https://github.com/asciidoctor/asciidoctorj-reveal.js[this project]) ifeval::['{branch}' == 'master'] NOTE: You're viewing the documentation for an upcoming release. If you're looking for the documentation for the current release or an older one, please click on the appropriate link below: + -{uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest release) +{uri-project-repo}/tree/v3.1.0#readme[3.1.0] (latest release) &hybull; +{uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest from 2.x series) +&hybull; {uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest from 1.1 series) &hybull; {uri-project-repo}/tree/maint-1.0.x#readme[1.0.x] &hybull; {uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with RevealJS 2.x) @@ -104,22 +107,22 @@ $ bundle --path=.bundle/gems --binstubs=.bundle/.bin . Optional: Copy or clone reveal.js presentation framework. Allows you to modify themes or view slides offline. - $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git + $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git === Rendering the AsciiDoc into slides . Create content in a file (*.adoc, *.ad, etc.). See examples in <<Syntax Examples>> section to get started. . Generate HTML presentation from the AsciiDoc source $ bundle exec asciidoctor-revealjs \ - -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 CONTENT_FILE.adoc + -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@3.9.2 CONTENT_FILE.adoc . If you did the optional step of having a local reveal.js clone you can convert AsciiDoc source with $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc @@ -227,11 +230,11 @@ * {uri-project-repo}/releases[Download the executable] for your platform and make it executable with `chmod` or using the files properties' user interface. * Copy or clone the reveal.js presentation framework in the directory where you will build your slidedeck. Here we do a shallow clone of the repo: - $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git + $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git === Convert AsciiDoc into slides Open a terminal where the executable is and type: @@ -526,23 +529,42 @@ 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: +reveal.js is well integrated with https://highlightjs.org/[Highlight.js] for syntax highlighting. +Asciidoctor reveal.js supports that. +You can activate Highlight.js syntax highlighting (disabled by default) by setting the `source-highlighter` document attribute as follows: [source, asciidoc] ---- = Presentation Title // [...] other document attributes :source-highlighter: highlightjs ---- -Once enabled you can write code blocks as usual: +[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 @@ -567,11 +589,12 @@ print "$0: hello world\n" ---- .... [NOTE] -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). +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 @@ -590,13 +613,111 @@ 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 -=== Asciidoctor-reveal.js specific roles +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] @@ -626,10 +747,21 @@ 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 `<a>` 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 <<examples/links.adoc#,links.adoc>> and <<examples/links-preview.adoc#,links-preview.adoc>> 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`. @@ -761,11 +893,46 @@ 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 `<head>` element +header:: content is inserted before the first child of the `<div class="slides">` element (before the slides) +footer:: content is inserted after the last child of the `<div class="slides">` 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] +---- +<script src="https://platform.twitter.com/widgets.js"></script> +---- + +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]. @@ -792,11 +959,11 @@ |:revealjsdir: |<file\|URL> |Overrides reveal.js directory. Example: ../reveal.js or -https://cdnjs.com/libraries/reveal.js/3.7.0[https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0]. +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 @@ -834,13 +1001,17 @@ 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. +|Push each slide change to the browser history. Implies `hash: true` |:revealjs_keyboard: |*true*, false |Enable keyboard shortcuts for navigation. @@ -862,10 +1033,18 @@ |: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: @@ -890,10 +1069,18 @@ 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: |<integer> |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. @@ -910,22 +1097,43 @@ |<integer> |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: +|<integer> +|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: +|<integer> +|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: +|<integer> +|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 `data-preview-link` and `data-preview-link="false"` to customise each link individually +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. @@ -937,12 +1145,19 @@ |none, *fade*, slide, convex, concave, zoom |Transition style for full page slide backgrounds. |:revealjs_viewDistance: |<integer> -|Number of slides away from the current that are visible. Default: 3 +|Number of slides away from the current that are visible. +Default: *3*. +|:revealjs_mobileViewDistance: +|<integer> +|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: |<file\|URL> |Parallax background image. Defaults to none @@ -999,10 +1214,17 @@ 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 @@ -1017,22 +1239,11 @@ ---- :revealjs_plugin_zoom: disabled :revealjs_plugin_notes: disabled ---- -reveal.js ships with a plugin that allows to create a PDF from a slide deck. -To enable this plugin, set the `revealjs_plugin_pdf` attribute. ----- -:revealjs_plugin_pdf: enabled ----- - -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. - -TIP: To work properly, this plugin requires a Chrome-based browser. - - === 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 @@ -1056,9 +1267,31 @@ 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.