====== QnA Plugin ======

---- plugin ----
description: Custom formatting for Q&A (FAQ) sections
author     : Mykola Ostrovskyy
email      : dwpforge@gmail.com
type       : syntax
lastupdate : 2023-06-18
compatible : hrun, Ponder Stibbons, Hogfather, Igor, Jack Jackrum, Kaos
depends    : 
conflicts  : 
similar    : wrap, faq
tags       : formatting, boxes
downloadurl: https://github.com/dwp-forge/qna/archive/v.2023-06-18.zip
bugtracker : https://github.com/dwp-forge/qna/issues
sourcerepo : https://github.com/dwp-forge/qna
----

There are number of ways to organize a FAQ sections on a DokuWiki page that use (abuse) different syntax elements to present the questions and answers. The QnA plugin introduces semantically clear syntax for both questions and answers plus a convenient way to create a table of contents for the FAQ.


===== Download and Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

  * [[https://github.com/dwp-forge/qna/archive/v.2023-06-18.zip|qna-2023-06-18]]


===== Syntax =====

{{ https://images2.imgbox.com/53/76/4NHxycVI_o.png?300}}

The basic QnA block starts with a question and is followed by one or more optional answers. The questions are marked by triple question mark at the start of a line, the answers --- with triple exclamation mark:

<code>
??? How do I format a question?
!!! Put triple question mark at the start of a line followed by the question title.
</code>

The first line of the question (must be on the same line as the ''???'' marker) is used as the question title and like DokuWiki headlines does not support any formatting. The rest of the text between the title and the first answer is treated as the question details and can contain almost any DokuWiki syntax (except of headers). This also applies to the answer block --- no syntax limitations.

Normally question and answer blocks span until the start of the next block or to the next section. If you want to mix QnA syntax with plain text you can explicitly terminate the block by the question block marker without the question title:

<code>
??? How do I terminate a QnA block?
What if I want to put some text after the block and that text doesn't
belong to the answer?

!!! Put triple question mark at the start of a line.
???

This text is not part of the answer.
</code>

You can organize multiple questions into sections using slightly modified headline syntax:

<code>
=?==== Level 1 headline ======
=?=== Level 2 headline =====
=?== Level 3 headline ====
=?= Level 4 headline ===
</code>

The normal headlines are still respected and may be used together with customized ones. The only difference is that they are not shown in the QnA table of contents.

The QnA TOC can be inserted with ''~~QNA~~'' or ''~~FAQ~~'' syntax. It will be rendered as an unordered list of all questions on the current page. Note that due to implementation constrains the TOC for the current page may be not properly updated in preview during the page editing. Instead of the current page you can insert TOC for other pages by adding the page names to the ''~~QNA~~'' syntax:

<code>
~~QNA faq:installation faq:sequrity faq:usage~~
</code>

When multiple page names are specified the plugin will combine information from all pages into a single TOC.


===== Configuration =====

The plugin supports multiple visual styles, and you can select the one you like the most using [[plugin:config|Configuration Manager]]. Look for "QnA" in plugin configuration section.


===== Style customization =====

All elements rendered by QnA plugin are wrapped into containers with distinct class names. This allows to easily customize their look with a [[devel:css#user_styles|user-defined CSS style sheet]]. The figure below shows different HTML elements generated by the plugin along with their ''class'' attributes:

{{ https://images2.imgbox.com/7b/77/yLUEHBQe_o.png |Styling}}


===== Version History =====

==== 2023-06-18 ====

  * Fixed compatibility with DokuWiki Jack Jackrum

==== 2022-07-06 ====

  * Fixed compatibility with PHP8

==== 2017-09-25 ====

  * Fixed trimming of multibyte characters in question identifiers

==== 2017-07-27 ====

  * Added multiple formatting styles
  * Added configuration option for style selection

==== 2017-06-20 ====

  * Fixed background color selection for question and answer blocks
  * Fixed linking from TOC to QnA sections

==== 2016-02-27 ====

  * Respect ACL during TOC generation
  * Fixed PHP 7 compatibility

==== 2015-02-16 ====

  * Various minor bug fixes

==== 2009-12-13 ====

  * First public release


===== Bugs and Feature Requests =====

Please report bugs or feature requests at the [[https://github.com/dwp-forge/qna/issues|bug tracker]].