README.adoc in asciidoctor-bespoke-1.0.0.alpha.1 vs README.adoc in asciidoctor-bespoke-1.0.0.alpha.2

- old
+ new

@@ -1,8 +1,8 @@ = {project-name} Dan Allen <https://github.com/mojavelinux> -v1.0.0.alpha.1, 2016-03-25 +v1.0.0-alpha.2, 2023-10-28 // Settings: :idprefix: :idseparator: - ifndef::env-github[] :icons: font @@ -10,10 +10,11 @@ ifdef::env-github,env-browser[] :toc: preamble :toclevels: 2 endif::[] ifdef::env-github[] +:status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: @@ -44,47 +45,56 @@ :uri-rvm: http://rvm.io :uri-slim-docs: http://www.rubydoc.info/gems/slim/ :uri-svgo: https://github.com/svg/svgo :uri-yo-bespoke: https://github.com/bespokejs/generator-bespoke +ifdef::status[] +image:https://img.shields.io/gem/v/asciidoctor-bespoke.svg?label=gem[gem badge, link=https://rubygems.org/gems/asciidoctor-bespoke] +endif::[] + An {uri-asciidoctor}[Asciidoctor] converter that generates the HTML component of a {uri-bespoke}[Bespoke.js] presentation from AsciiDoc. == Overview -The goal of {project-name} is to enable you to craft HTML-based presentations from reusable content while avoiding the tedium of writing HTML markup. +The goal of {project-name} is to enable you to craft HTML-based presentations from reusable content while avoiding the tedium of writing HTML. This library satisfies that goal by providing a converter that generates the HTML component of a Bespoke.js presentation from an AsciiDoc document. In other words, it allows you to use AsciiDoc in place of HTML (or an HTML template language like Jade) in your Bespoke.js project. (You still need to add an ample amount of CSS in order to achieve the presentation style you want). The converter works in tandem with a typical JavaScript project structure based on npm and Gulp. -npm is used to manage dependencies, while a Gulp build is used to combine and "`browserify`" the JavaScript, compile the CSS, execute this converter (to convert AsciiDoc to HTML), launch the preview server and publish the presentation files. +npm is used to manage dependencies. +A Gulp build is used to combine and "`browserify`" the JavaScript, compile the CSS, execute this converter (to convert AsciiDoc to HTML), launch the preview server and publish the presentation files. The converter is implemented as a collection of Slim templates, which are packaged for your convenience as an Asciidoctor converter. The templates come into play when you want to customize the HTML the converter generates. This guide explains how to integrate the {project-name} converter into an existing Bespoke.js presentation project and how to write slides in AsciiDoc. == Prerequisites -In order to use {project-name}, you must satisify the prerequisites of both Bespoke.js and Asciidoctor. +In order to use {project-name}, you must satisfy the prerequisites of both Bespoke.js and Asciidoctor. +You also need a Bespoke.js project. -For Bespoke.js:: +=== For Bespoke.js + . {uri-nodejs}[Node.js] >= 0.12 footnote:[We strongly recommend using {uri-nvm}[nvm] to manage Node.] . {uri-gulp}[Gulp] (command line interface only) $ npm install -g gulp-cli -For Asciidoctor:: +=== For Asciidoctor . {uri-ruby}[Ruby] >= 2 footnote:[We strongly recommend using {uri-rvm}[RVM] to manage Ruby.] . {uri-bundler}[Bundler] $ rvm use 2.3.0 --install # (optional) $ gem install bundler +=== Bespoke.js Project + Naturally, you'll also need a Bespoke.js project, just as you would for any Bespoke.js presentation. -If you don't yet have a Bespoke.js project, you can clone the following starter project: +If you don't yet have a Bespoke.js project, you can clone the provided https://github.com/opendevise/presentation-bespoke-starter[starter project]: $ git clone https://github.com/opendevise/presentation-bespoke-starter Alternatively, you can use the {uri-yo-bespoke}[Yeoman generator for Bespoke.js] to initialize your project. As a word of warning, that generator has become substantially out of date. @@ -92,15 +102,15 @@ == Integrating AsciiDoc into a Bespoke.js Project Once you've initialized your Bespoke.js project, the next task is to replace Jade with AsciiDoc. -TIP: If you're creating a new project using the starter project previously mentioned, and you switch to the `asciidoc` branch in that repository, you can skip the steps in this section and jump ahead to <<Creating Slides in AsciiDoc>>. -If you're curious, you can review https://github.com/opendevise/presentation-bespoke-starter/compare/asciidoc?diff=split[the diff of the changes] this section goes on to cover. +TIP: If you're creating a new project using the starter project previously mentioned, you can switch to the https://github.com/opendevise/presentation-bespoke-starter/tree/asciidoc[asciidoc branch] in that repository to skip past the steps in this section and jump ahead to <<Creating Slides in AsciiDoc>>. +If you're curious, you can review https://github.com/opendevise/presentation-bespoke-starter/compare/asciidoc?diff=split[a diff] that contains the changes this section goes on to cover. The first step is to configure Bundler to fetch and install the required gems. -Create the file [.path]_Gemfile_ at the root of the project and populate it with the following content: +Create a file named [.path]_Gemfile_ at the root of the project and populate it with the following content: .Gemfile [source,ruby,subs=attributes+] ---- source 'https://rubygems.org' @@ -108,21 +118,21 @@ gem 'asciidoctor-bespoke', '{latest-release}' # To use the latest version from git, use the following line instead: #gem 'asciidoctor-bespoke', github: 'asciidoctor/asciidoctor-bespoke' ---- -Next, run `bundle` from the root of the project to install the gems and any dependencies: +Next, run `bundle` from the root of the project to install the gems and any dependencies they have: $ bundle [TIP] ==== -If you want to install the gems inside the project, you can pass the `--path` argument to `bundle`: +If you want to install the gems inside the project, you can pass the `--path` argument to `.bundle/gems`. - $ bundle --path=rubygems + $ bundle --path=.bundle/gems -The `bundle` command will remember this setting on subsequent invocations. +The `bundle` command will remember this setting for all successive invocations. ==== The next step is to get the converter to generate the HTML from AsciiDoc when the presentation build runs. We'll repurpose the task that currently generates HTML from Jade for this purpose. @@ -135,21 +145,21 @@ Save the file and run `npm i` to install the new packages into your project: $ npm i -Open [.path]_gulpfile.js_ and add the following entries to the list of requires at the top: +Open [.path]_gulpfile.js_ and add the following entries to the list of `require` calls at the top of the file: .gulpfile.js (snippet) [source,js] chmod = require('gulp-chmod'), exec = require('gulp-exec'), -In the same file, remove the existing `html` task and replace it with the one below: +Also in [.path]_gulpfile.js_, replace the existing `html` task with the one below: .gulpfile.js (snippet) -[source,js,subs=attributes+] +[source,js] gulp.task('html', ['clean:html'], function() { return gulp.src('src/index.adoc') .pipe(isDist ? through() : plumber()) .pipe(exec('bundle exec asciidoctor-bespoke -o - src/index.adoc', { pipeStdout: true })) .pipe(exec.reporter({ stdout: false })) @@ -159,23 +169,23 @@ .pipe(connect.reload()); }); //<1> Add `bundle exec` in front of the `asciidoctor-bespoke` command if you're using the development version from git. -Finally, if you want the build to watch the AsciiDoc file(s) for changes, look for the following line in the watch task: +Finally, to get the build to watch the AsciiDoc file(s) for changes, look for the following line in the watch task in [.path]_gulpfile.js_: .gulpfile.js (snippet) [source,js] - gulp.watch('src/**/*.jade', ['html']); + gulp.watch('src/**/*.pug', ['html']); and replace it with: .gulpfile.js (snippet) [source,js] gulp.watch('src/**/*.adoc', ['html']); -The build is now ready. +The build is now ready! Before we can use our new task, we need to create slide content in AsciiDoc. == Creating Slides in AsciiDoc Writing AsciiDoc to create slides is pretty much the same as writing AsciiDoc for any another purpose. @@ -196,11 +206,11 @@ == First Topic ---- Believe it or not, that's all it takes to make a presentation! -Here's a close approximation of the HTML the converter generates for the simple presentation shown above. +Here's a close approximation of the HTML the converter generates from the example shown above (formatted for clarity). [source,html] ---- <!DOCTYPE html> <html lang="en"> @@ -225,16 +235,16 @@ </html> ---- There are a few things you should notice: -* Each slide is represented as a `<section>`, which is generated for each section title. - - At runtime, Bespoke.js will add additional classes to each `<section>`, including `bespoke-slide`. +* Each slide is represented as a `<section>`, which is generated per section title. + - At runtime, Bespoke.js adds additional classes to each `<section>`, including `bespoke-slide`. * The title slide has the class `title` and uses an `<h1>` heading. * The section title for each content slide gets put in an `<h2>` heading. * The presentation is wrapped in an `<article>` element with the class `deck`. - - At runtime, Bespoke.js will add additional classes to `<article>`, including `bespoke-parent`. + - At runtime, Bespoke.js adds additional classes to `<article>`, including `bespoke-parent`. * CSS is used to accomplish most of the styling and layout, so you'll need to spend some time on it. * The JavaScript and CSS to power the Bespoke.js presentation are loaded from the [.path]_build/_ folder. Of course, this is not a very interesting presentation, so let's dig a bit deeper. @@ -254,10 +264,11 @@ * twitter * avatar (an image path relative to imagesdir) * preamble content NOTE: The title slide is a built-in transform mapped to the {uri-repo-file-prefix}templates/slim/slide_title.html.slim[slide_title.html.slim] template, which you can override. +See <<Custom Transforms>> for information about where to put this file and how to load it. You'll need to incorporate CSS (optionally using the Stylus syntax) to arrange and style the title page. Here's an example of an AsciiDoc document that generates a title slide that is fully populated: [source,asciidoc] @@ -268,16 +279,16 @@ :position: Developer Advocate :twitter: @asciidoctor :avatar: author-avatar.png :!sectids: -Additional content for title slide. +Additional content for the title slide. == First Topic ---- -If you don't want the title slide to be created, add the `noheader` attribute to the document header (or simply don't include a document header). +If you don't want the title slide to be created, add the `noheader` attribute to the document header. .A presentation without a title slide [source,asciidoc] ---- = My Awesome Presentation @@ -285,10 +296,12 @@ :noheader: == First Topic ---- +Another option is to simply leave out the document header altogether. + === Content Slides Each content slide is created from a level-1 section title. The section title becomes an `<h2>` heading. The remainder of the content in the section is placed below this heading. @@ -305,21 +318,21 @@ * Demo * Discussion ---- While many of your slides may have a primary heading--perhaps as the only content on the slide--there are many slide types that don't require a heading. -You can indicate a slide without a heading by using `!` as the section title. +You can mark a slide without a heading by using `!` as the section title. Here's an example: .A slide with only content (i.e., an anonymous slide) [source,asciidoc] ---- == ! image::chart.svg[] ---- -If you want to assign a title to a slide, but just not show it, you can use the `conceal` option. +If you still want to assign a title to a slide, but not show it, you can add the option named `conceal`. .A slide with a concealed heading [source,asciidoc] ---- [%conceal] @@ -334,10 +347,19 @@ ---- = !An Amazing Chart image::chart.svg[] ---- +You can also add a named hash to a slide so you get a URL like `/#intro` instead of `/#3`. + +.A slide with a named hash (aka named route) +[source,asciidoc] +---- +[#intro] += Intro +---- + Notice how we're keeping the concerns of content and presentation cleanly separated. Using very little AsciiDoc, you're able to describe a lot of different functionality. There doesn't even have to be a direct, literal mapping between the AsciiDoc and the HTML. Instead, you should think of the AsciiDoc as a DSL for content. @@ -360,10 +382,11 @@ * twitter * email * section content (if any) NOTE: The speaker slide is a built-in transform mapped to the {uri-repo-file-prefix}templates/slim/slide_speaker.html.slim[slide_speaker.html.slim] template, which you can override. +See <<Custom Transforms>> for information about where to put this file and how to load it. Here's a rough approximation of the HTML generated for the speaker slide: [source,html] ---- @@ -519,10 +542,11 @@ You can use CSS to introduce additional build effects. The effects supported out of the box are as follows: * fade * vanish +* spotlight (planned) * replace (planned) The CSS in the <<Build Configuration>> section implements these effects. === Canvas Image @@ -651,10 +675,47 @@ **** ---- To learn more about how to setup a presentation console, see the https://github.com/opendevise/bespoke-onstage[bespoke-onstage plugin]. +=== 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 Bespoke converter. + +Currently, there are three insertion locations for docinfo content in a Bespoke document: + +head:: content is inserted after the last child of the `<head>` element +header:: content is inserted before the first child of the `<article>` element (before the slides) +footer:: content is inserted after the last child of the `<article>` element (after the slides) + +The content you want to insert goes into a sibling file of the slide deck document with the following filename pattern: + + docinfo-<location>-bespoke.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-bespoke.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. + +If you want to include content in every slide, we recommend using a http://asciidoctor.org/docs/user-manual/#extension-points[tree processor extension]. +The tree processor would first query for all the level-1 sections in the document (which get transformed into slides), then append one or more blocks to each of the matched sections. +The tree processor could even read this content from a shared file. +In the future, the converter may support docinfo insertions per slide. + === Custom Transforms While conversion from AsciiDoc is meant to save you time producing common slide types, there are cases when you find yourself going against the grain or exceeding the limits of what CSS can handle. This situation is normal. The truth is, certain slides require an HTML layout that is tailored to the content. @@ -799,9 +860,9 @@ Bespoke.js was created by https://github.com/markdalgleish[Mark Dalgleish] and has received contributions, mostly in the form of plugins, from many other individuals in the Bespoke.js ecosystem. === Copyright -Copyright (C) 2015-2016 Dan Allen and the Asciidoctor Project. +Copyright (C) 2015-present Dan Allen and the Asciidoctor Project. +Use of this software is granted under the terms of the MIT License. -Free use of this software is granted under the terms of the MIT License. -See the <<LICENSE#,LICENSE>> file for details. +See the link:LICENCE[LICENSE] file for the full license text.