README.adoc in asciidoctor-revealjs-4.0.1 vs README.adoc in asciidoctor-revealjs-4.1.0.rc2

- old
+ new

@@ -16,12 +16,13 @@ :warning-caption: :warning: endif::[] :uri-project-repo: https://github.com/asciidoctor/asciidoctor-reveal.js :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-revealjs-home: https://revealjs.com +:uri-revealjs-gh: https://github.com/hakimel/reveal.js/blob/v3.9 +:uri-revealjs-doc: {uri-revealjs-gh}/README.md :uri-nodejs-download: https://nodejs.org/en/download/ :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] @@ -42,32 +43,22 @@ * 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/v3.1.0#readme[3.1.0] (latest release) +{uri-project-repo}/tree/v4.0.0#readme[4.0.1] (latest from 4.x series) &hybull; -{uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest from 2.x series) +{uri-project-repo}/tree/v3.1.0#readme[3.1.0] (latest from 3.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) +{uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with reveal.js 2.x) endif::[] == Ruby Setup -NOTE: asciidoctor-reveal.js is now a Ruby Gem. -To ensure repeatability, we recommend that you manage your presentation projects using bundler. +NOTE: To ensure repeatability, we recommend that you manage your presentation projects using http://bundler.io/[bundler]. -For a quick start clone our https://github.com/obilodeau/presentation-revealjs-starter[starter repository] and follow instructions there. - -For more complete instructions, read on. - - === Prerequisites . Install http://bundler.io/[bundler] (if not already installed) using your system's package manager or with: $ gem install bundler @@ -127,11 +118,34 @@ $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc TIP: If you are using https://pages.github.com/[GitHub Pages], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch. +=== Features Unique to the Ruby CLI +Starting with 4.0.0 you can specify a set of custom templates to use instead of the ones provided by this project. +This can help you achieve even more concise AsciiDoc syntax and integration with reveal.js at the cost of more maintenance. + +To use it, add the following dependencies to your `Gemfile`: + + gem 'tilt', '~>2.0' + gem 'slim', '~>4.0' + +Then install the dependencies with: + + $ bundle install + +The feature is activated with the `--template-dir` or `-T` option: + + $ bundle exec asciidoctor-revealjs -T templates/ CONTENT_FILE.adoc + +Any individual template file not provided in the directory specified on the command-line will fall back to the template provided by your version of Asciidoctor reveal.js. +Refer to our https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates[templates] for inspiration. + +This feature hasn't been ported to the JavaScript CLI (and API) or the standalone executables. + + == Node / JavaScript Setup === Prerequisites First you must install and configure {uri-nodejs-download}[Node] on your machine. @@ -299,11 +313,11 @@ * tell anecdote * make a point -- ---- -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]. +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-doc}#speaker-notes[speaker notes]. Other syntax exists to create speaker notes, see `examples/speaker-notes.adoc`. Starting with Reveal.js 3.5 speaker notes supports configurable layouts: image:https://cloud.githubusercontent.com/assets/629429/21808439/b941eb52-d743-11e6-9936-44ef80c60580.gif[] @@ -386,11 +400,11 @@ == Slide Three Is very yellow ---- -Slide Three applies the attribute {uri-revealjs-gh}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag. +Slide Three applies the attribute {uri-revealjs-doc}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag. Anything accepted by CSS color formats works. === Background images @@ -403,11 +417,11 @@ ---- 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. +See the {uri-revealjs-doc}#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. @@ -441,11 +455,11 @@ ---- [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. +See {uri-revealjs-doc}#video-backgrounds[the relevant reveal.js documentation] for details. Note that the `data-` prefix is not required in asciidoc files. === Background iframes @@ -455,11 +469,11 @@ ---- [%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. +See {uri-revealjs-doc}#iframe-backgrounds[the relevant reveal.js documentation] for details. === Slide Transitions [source, asciidoc] @@ -473,11 +487,11 @@ == Speed Choose from three transition speeds: default, fast or slow! ---- -See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details. +See {uri-revealjs-doc}#slide-transitions[the relevant reveal.js documentation] for details. === Fragments [source, asciidoc] @@ -490,13 +504,13 @@ * 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]. +This is what `reveal.js` calls {uri-revealjs-home}/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 +Here is {uri-revealjs-doc}#fragments[the relevant reveal.js documentation] on the topic. Note that only `fade-in` is supported for lists at the moment. === Stretch class attribute @@ -508,11 +522,11 @@ 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]. +See {uri-revealjs-doc}#stretching-elements[reveal.js documentation on stretching elements]. === Videos In addition to <<Background videos,background videos>>, videos can be inserted directly into slides. @@ -541,11 +555,11 @@ // [...] 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 @@ -557,11 +571,11 @@ ``` // 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] .... @@ -610,11 +624,11 @@ 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 +Here is {uri-revealjs-doc}#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: @@ -711,11 +725,37 @@ [.column] image::large-image.png[] .... +Text alignment of columns is also supported. +Text content on individual columns can be aligned with `has-text-left`, `has-text-right` and `has-text-justified` CSS classes. +[source, asciidoc] +.... +[.columns] +== Column Text Alignment + +[.column.has-text-left] +-- +Something Short + +Something So Long That We Need It Aligned +-- + +[.column.has-text-justified] +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + +[.column.has-text-right] +-- +Something Short + +Something So Long That We Need It Aligned +-- +.... + + === 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] @@ -767,11 +807,11 @@ 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. +Read {uri-revealjs-doc}#slide-backgrounds[the relevant reveal.js documentation] to understand what attributes need to be set. Keep in mind that for title slides you must replace `data-` with `title-slide-`. ifeval::[{safe-mode-level} >= 20] See <<examples/title-slide-image.adoc#,title-slide-image.adoc>>. endif::[] @@ -850,11 +890,11 @@ 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 `<section>` tags. +Reveal.js supports a {uri-revealjs-doc}#slide-states[data-state] tag that can be added on slides which gets rendered into `<section>` 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] @@ -943,11 +983,11 @@ |=== |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]. +|Chooses one of reveal.js`' {uri-revealjs-doc}#theming[built-in themes]. |:revealjs_customtheme: |<file\|URL> |Overrides CSS with given file or URL. Default is disabled. @@ -1035,11 +1075,11 @@ |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 +|See {uri-revealjs-doc}#navigation-mode for details |:revealjs_shuffle: |true, *false* |Randomizes the order of slides each time the presentation loads @@ -1210,18 +1250,18 @@ |=== 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 +{uri-revealjs-gh}/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. +Follow {uri-revealjs-doc}#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 @@ -1251,10 +1291,10 @@ . 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. +Read {uri-revealjs-doc}#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