Asciidoctor Question is a set of Asciidoctor extensions that allows you to add questions as multiple choice and gap text. The questions are defined using plain text in your AsciiDoc document.

Installation and Update

There are two options to install Asciidoctor Question. The first is to use gem install on the command line:

$ gem install asciidoctor-question

The second is to add the following entry to your project’s Gemfile.

Gemfile

gem 'asciidoctor-question', '~> 0.5'

and execute bundle in the command line.

$ bundle

To update asciidoctor-question type

$ gem update asciidoctor-question

Creating a Question

A question is written inside a literal block, which needs two attributes.

Anatomy of a question

[question, question-type] // <b class="conum">(1)</b> <b class="conum">(2)</b>
....                      // <b class="conum">(3)</b>
Question in appropriate syntax
....

1. The first positional attribute in the attribute list specifies that this block is a question.

2. The second positional attribute defines the type of this question (mc or gap)

3. Place the attribute list directly on top of the delimited literal block (....). You can also use an example (====) or open block (--) as an alternative.

The following question types are available:

Question Type	input	output
mc	[question, mc] .... Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. - [X] ipsum - [ ] eltir - [X] ut ....
gap	[question, gap] .... At vero eos et __accusam__ et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea __takimata sanctus est Lorem__ ipsum dolor sit amet. Lorem __ipsum dolor sit amet__, consetetur sadipscing elitr, sed diam nonumy __eirmod tempor invidunt__ ut labore et dolore magna aliquyam erat, sed diam voluptua. ....

Generating a Question Document from a Terminal

You can load Asciidoctor question in a terminal using the -r flag.

$ asciidoctor -r asciidoctor-question sample.adoc

You can also use Asciidoctor question with other converters, such as Asciidoctor PDF. Asciidoctor-pdf is also loaded with the -r flag.

$ asciidoctor -r asciidoctor-question -r asciidoctor-pdf -b pdf sample.adoc

Or, you can invoke Asciidoctor and the PDF converter with the asciidoctor-pdf command. The command implicitly sets the -r and -b flags for PDF output.

$ asciidoctor-pdf -r asciidoctor-question sample.adoc

Advanced Usage

Generating PDF with solutions

With the attribute :solution: it is possible to generate a pdf file which contains the questions with its solutions.

$ asciidoctor -r asciidoctor-question -r asciidoctor-pdf -b pdf -a solution sample.adoc

You can also add the :solution: attribute to your asciidoc file.