Controlling Question Numbering

The qnum directive provides control over question numbering.


The general format of the qnum directive is:

.. qnum::
   :prefix: character prefix before assessment number
   :suffix: character prefix after assessment number
   :start: start numbering with this value

The qnum directive does not use a content block or a unique id.

It does not directly render anything itself, but changes question number labels in other assessments.

If only one qnum directive exists in the file, then the qnum directive effects all assessments in the current file.

If more than one qnum directive exists in the file, then changes created by the qnum directive affect the file sequentially. All questions that follow the qnum directive use the most recently defined qnum.

qnum values affect only the current file.

Required Arguments

No arguments are strictly required, however, a qnum directive with no options has no effect.

Optional Arguments


String. Define characters before the question number.

The default is no prefix for Multiple Choice and Q- for Parsons Problems and Short Answer.


String. Define characters after the question number.

The default is no suffix defined.


Integer. Define the start for question numbering. Must be > 0.

The first question encountered will begin with this number and increment by 1 afterwards.

Languages supported

Not applicable.

Sphinx configuration options

No directive specific configuration options exist.



Known limitations

Not all Runestone assessments currently render question numbers. Those that do are:

Those that do not:

If every assessment in a file exists within a Tab Groups container, then the qnum directive has no effect. If even a single assessment is outside a tab group, then assessments are numbered as expected, both those in and out of tab containers.

The :suffix: option does not change the : character between the number / suffix and whatever follows. That is, the : is not considered part of the suffix.



.. qnum::
   :prefix: Ex-
   :start: 1

Changes question numbering as follows:

The following assessment is a timed exam that restarts question numbering and appends to the numbers:

.. qnum::
   :suffix: -timed
   :start: 1

Because the :prefix: was not set, the existing prefix Ex continues to be used.

Next Section - Extension Authors