No commit activity in last 3 years
No release in over 3 years
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.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 1.13
~> 12
~> 3.5

Runtime

 Project Readme

Asciidoctor Question

Gem Version MIT License

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] // (1) (2)
....                      // (3)
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
....
mc

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.
....
gap

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.