Lists and Procedures – Paligo

Paligo has many different types of lists and procedures that you can use in your content. Each type of list has a different purpose and underlying structure, for example, there are bullet lists, procedures, numbered lists, and specialized lists for questions and answers and much more.

To get started with lists, we recommend that you learn about the commonly used Types of Lists. You can then refer to the relevant help articles to learn how to create lists, and order, reuse, and convert them.

You can also check out this video for some tips on working with lists.

Types of Lists

The most commonly used list types are available under the Edit tab in the Toolbar.

Unordered lists

Also known as bullet lists or itemized lists gives each list item has a disc prefix by default. Use these for lists where the order of the list items is not important.

Example of unordered list
Ordered lists

Also known as numbered lists gives each list item a number prefix. Use these for lists where the order is important, but it is not related to step-by-step instructions. For example a topic with chart positions, such as a "Top 10 reasons to recycle the battery" then the order is important, but the sequence is not step-by-step instructions.

Example of ordered list
Procedures

Use procedures for step-by-step instructions. Each list item is a step and the structure of the elements is designed specifically for a process.

Example of procedure
Checklists

Also known as to-do lists gives each list items a checkbox prefix. For PDF, the boxes are blank so that they can be checked. For HTML, the boxes are selectable.

To find out how to add checklists, see Checklists.

Other Available List Types

For other types of lists, use the Element Context Menu to add the appropriate list element, for example variablelist or qandaset.

Tasks - Tasks are more formal versions of procedures that have additional elements available that cannot be used with regular procedures, see Tasks.
Question-and-Answer Lists - Use these lists for frequently-asked-questions lists with a series of questions and answers. To find out how to create question-and-answer lists, see Question and Answer Lists (FAQs).
Callout Lists -Callout lists are designed for adding annotations to code samples in your content. You can use them to add "hotspots" to your code example with explanations for those markers shown below.

For example, the following image shows a code sample that has two "hotspots" in the code. Below the code sample, there are text descriptions to provide the reader with more information

To find out more, see Annotate Code Blocks.
Variable Lists - Also known as description lists, these lists look like borderless tables and are for describing terms. To find out more, see Variable List (Description List).

Create a List or Procedure

You can add procedures and different types of lists to your topics. The most commonly used Types of Lists are available under the Edit tab in the Toolbar.

Unordered list also known as a bullet list.
Ordered list also known as numbered list or itemized list. Do not confuse it with a procedure, see Types of Lists.
Procedure used for step-by-step instructions.
Checklist used for To-Do lists with checkboxes.

For other types of lists, use the Element Context Menu to add the appropriate list element, for example, variablelist or qandaset. To access the element context menu, press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac).

Tip

To speed up your work in Paligo, see Keyboard Shortcuts.

Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Position the cursor where the list is to be added.

The cursor has be to placed in a valid position, such as inside an empty para element or immediately after a para.
Select the Edit tab in the toolbar.
Select a type of list from the toolbar.

Paligo creates the first list item or step automatically.
Enter the text for the first list item or step.
Press Enter to add new list items or steps. ⏎
Select Save.

Tip

More useful tips when working with lists and procedures:

To reuse parts of a list, see Reuse a Sequence of List Items
To copy lists or specific list items, see Copy Content
To move lists or specific list items, see Move Content
To add extra content inside a list, see Add Content Inside a List Item or Step
To remove a list, a specific list item or step, see Delete Content Inside Topics.

Convert a List

This section describes how to convert a list into a different list type.

Select the list or procedure in the Element Structure Menu.
Select a list type from the toolbar.
Select Confirm to change into a new list type.
Select Save.

Set Starting Number

By adding attributes, you can control the numbering of an ordered list. You can set it to start at a specific number or continue the numbering from a previous list.

Select the ordered list in the Element Structure Menu.
Select Go to element.
Add one of these attributes in the Element Attributes Panel:
- Startingnumber to specify the first number the ordered list will use. Add the starting number.
- Continuation and set the value to continues to make the list continue the numbering from a previous list.
Select Preview to see the changes to the numbering.
Select Save.

Select Numeration Type

By adding the numeration attribute, you can adjust the numeration type for the ordered list. You can choose between:

arabic 1, 2, 3 (default)
upperalpha A, B, C
loweralpha a, b, c
upperroman I, II, III
lowerroman i, ii, iii

Select the ordered list in the Element Structure Menu
Select Go to element.
Add the numeration attribute in the Element Attributes Panel.
Select desired numeration type from the menu.
Select Save.

Move a List Item or Step

There are several ways to change the order of the list items / steps in your lists and procedures.

Use the XML Tree View to see the list structure, and then drag and drop each list item / step to a different position.
Select the listitem/step, then select the listitem or step element in the element structure menu. Use the Move Up and Move Down options to change the position of the list item / step.
Select the list item / step and then use the keyboard shortcuts to move it up or down.

The keyboard shortcuts for Mac OS are:

Option ⌥ ↓ for down

Option ⌥ ↑ for up

The keyboard shortcuts for Windows are:

AltShift↓ for down

AltShift↑ for up

Split a List

To split a list into two separate lists:

Select the area between the list items/steps where you want the split to take place.
Select the Split icon on the Edit toolbar.

Paligo splits the list at the selected listitem/step. You now have two separate lists of the same type.

The second list is completely separate to the first list, with new numbering (if it is a numbered list). You can Convert a List or set attributes on the list without affecting the first list.

Merge Two Lists

You can merge two adjacent lists of the same type into one list. This is useful if you have:

Imported content that was perhaps not formatted correctly in the original version, resulting in lists being broken down into smaller separate lists.
Two lists that were previously separated by paragraphs or other content that has now been deleted.

To merge two adjacent lists:

Select any listitem or step in the first list that you want to merge. The first list is the list that is closest to the top of the topic.
In the element structure menu, select the element that represents the list as a whole, and then select Go to element. For example, if in step 1 you selected a step, then you should select the procedure element in the element structure menu.
Select the Merge toolbar icon.

Paligo will merge the list with the next list as long as:
- The current list and the next list are of the same type
- There is no content between the current list and the next list.
Check the box Use gateway to enable IP Allowlisting. Optional

Convert a List into Paragraphs

To "undo" a list so that it becomes a series of paragraphs instead:

Select a listitem/step in the list.
In the element structure menu, select the element that represents the list as a whole, and then select Go to element. For example, if in step 1 you selected a step, then you should select the procedure element in the element structure menu.
Select the icon for the type of list that you want to undo. For example, if you have a procedure list that you want to turn into paragraphs, select the procedure icon.

When you select the icon, Paligo converts the list into a series of para elements.

Convert a Group of Paragraphs into a List

You can quickly convert paragraphs into popular types of list by using the toolbar icons (or their keyboard shortcut equivalents). This can be useful when you have content that is written as paragraphs, but should really be procedures or lists. For example, if you have copied content from a plain text editor into para elements.

Select any part of the paragraph.
Select the toolbar icon for the type of list you want to create. For example, select the procedure icon to turn a paragraph into the first step of a procedure.
Repeat step 2 for any subsequent paragraphs.

Note

When you turn a paragraph into a list or procedure, Paligo automatically moves the cursor to the next paragraph. So if you have a group of paragraphs, you can keep selecting the toolbar icon to turn each subsequent para into a step.

Reuse Content in Lists

When you are creating lists or procedures, you may find that there are opportunities for content reuse. A common example is if you are documenting software and you have a "Select Save" option that appears over and over again. To follow best practices, rather than create multiple versions of that, you should write it once and reuse it in your various procedures.

To reuse text fragments (individual paragraphs) in your lists, position the cursor inside a list step, where the para element is valid. This could be inside the para that is added automatically for each step, or it could be after the first para inside the step, but before the next step. Then use the Reuse text feature to search for reusable text fragments, and insert one at the cursor position. To find out more, see Reuse Text Fragments.

Valid cursor positions for reusing text fragments in a list.

To reuse an entire list, create an informaltopic and add the structure of the list into that. You can then insert the informaltopic into other topics, wherever it is needed. But remember to organize your informal topics into a logical folder structure in the Content Manager, so that other writers will be able to find them more easily. To find out more, see Create an Informal Topic.

To reuse parts of a list in another list, see Reuse Items in a List.

Add Content Inside a List Item or Step

When you are writing lists and procedures, it is likely that you will need to add some extra content inside the step. This could be an extra paragraph, an image, or an admonition. In this article, we will explain how to do that. If you are looking for help on how to have a sublist inside another list, see Sublists.

To add content inside a list item or step:

Position the cursor so that it is outside the para element in the list item or step. (But still inside the list item or step).
You can now add other elements, such as images, admonitions, and other paragraphs. To add these, you can use the toolbar menu or the element context menu, just like when you add elements outside a list. The elements that you add will appear indented, so that they are aligned with the paragraph inside the list item or step.

Note

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).
To add a list item or step after the content inside the step, position the cursor so that it is outside the list item or step. Then press Enter to display the element context menu and select listitem or step, depending on the type of list you are using.
To end the list, select a position outside the list, after the last step. You can then add other elements, such as paragraphs if needed.

Check out this video as an example of how to add an image (the same principle applies if you want to add a table or anything else):

Adding an image to a procedure step

Optional and Required Steps in Procedures

Abstract

You can mark up steps so that they are optional or required. To do this, you use the performance attribute. Paligo then gives the steps an optional or required class that can be styled differently in HTML outputs by using CSS.

When you are writing step-by-step procedures, you may have some steps that are optional and some that the user must complete. To make these steps stand out, you may want to style them differently, and this requires the steps to be marked up differently in Paligo XML.

You can use the performance attribute to set a step to optional or required. When you publish to HTML, the step will have a class name for optional or required, so that it can be styled differently using CSS.

Note

Optional and required steps can only be styled differently for HTML outputs. If you need different styling for PDFs, a customization is required.

To use the performance attribute:

Create a procedure with steps.
Select a step. In the element structure menu, select the step element and then select Go to element.
In the Element attributes section, search for the performance attribute and then add it.

Note

If the performance attribute is not shown, check that you have selected the step element and not the para element that is inside the step.
Set the value of the performance attribute to:
- Optional for steps that are not a requirement. The user can choose whether they want to complete these steps.
- Required for steps that the user must complete.
Select Save.

Create a custom CSS file and add the styling for the optional and required steps to it. The classes you need to style are .step.optional and .step.required. For example, the following code adds "(Optional)" or "(Required)" before the paragraph in the step and also sets the font to bold.

.step.optional p:first-child:before { 
    content: '(Optional) '; 
    font-weight: bold; 
}  

.step.required p:first-child:before { 
    content: '(Required) '; 
    font-weight: bold; 
}

This example only works for English. But it is possible to have multi-lingual support with CSS:

/* For supporting multiple languages: */  

html[lang="sv"] .step.optional p:first-child:before { 
    content: '(Valfritt ) '; font-weight: bold; 
}  

html[lang="en"] .step.required p:first-child:before { 
    content: '(Required) '; font-weight: bold; 
}  

html[lang="sv"] .step.required p:first-child:before { 
    content: '(Obligatoriskt ) '; 
    font-weight: bold; 
}

Upload your CSS file to your HTML layout.

To find out more about creating custom CSS files and uploading them to your HTML layouts, see Style with CSS.
Publish to HTML, using the HTML layout from the previous step.

Sublists

When you are writing lists and procedures, you may find that you want to have a series of substeps inside a main step. For example, you might have a procedure with step-by-step instructions, and inside step 2 you want to have a bullet list of the options a user can choose from.

A topic in Paligo. It has a procedure with 4 steps. For step 2, there is a paragraph and then below it, an indented bullet list with two steps.

To create these "indent" lists, you can use the Indent option on the toolbar. Alternatively, you can use the element context menu to add the relevant elements.

The following sections explain how to work with indented sublists.

Create an Indented Sublist

To indent list items or steps:

Create the your main list or procedure. When you get to the position where you want to add an indented list, add the first step/listitem as though it was part of your main list.
Select the listitem/step that is going to be in your indent list. Then select the Indent icon on the toolbar. Paligo indents the step. For most of the list types, the indented step is now part of another sublist. Procedures are slightly different as they become steps inside a substeps element.
To continue the sublist, select the end of the the sublist step/listitem and press Enter. Paligo will create extra indented listitems/steps for you.
Add content to the sublist in the same way that you would add content to the main list.
To exit the sublist and return to the main list, position the cursor after the last step in the sublist and outside the sublist structure. Then press Enter to display the element context menu. Select the option for the next type of listitem/step in the main list.
Check the box Use gateway to enable IP Allowlisting. Optional

Convert a Sublist into a Different Type of List

If you want to change the type of sublist:

Select a listitem/step in your sublist.
Look at the element structure menu.

There is a main list element (1) and a sublist element (2).

The name of the sublist element will vary, depending on the type of the main list. For example, for an orderedlist, the sublist is another orderedlist, but for procedures, the sublist is called substeps.
Select the element for the sublist and then select Go to element.
Select the toolbar icon for the type of list you want, such as an itemized list. At the prompt, confirm that you want to change the type of list.

Convert a Sublist into Items in the Main List

Outdent a Sublist

Tasks

Tasks are a more formal structure for step-by-step procedures. They have a title and a procedure by default, and you can also add other task-exclusive elements to them, including:

tasksummary

Use to add a summary of the task, typically before the task's procedure. This gives readers an understanding of what they will achieve.
taskprerequisite

Use to add information about the things that need to be in place before the user starts the procedure. This could involve information about licenses, types of user account, subscription plans, or confirmation that other tasks have already been completed.
taskrelated

Use to add links to related tasks. This is usually added before or after the task's procedure.

Should you use tasks instead of regular procedures? It depends on the structure you want for your step-by-step instructions. If you want your procedures to have a title and any of the other task-related structural elements, use a task. But some people find this to be too structured, and they prefer to have no title and just the list of steps that comes with a regular procedure.

Note

Some of the task elements may require a customization for styling in PDF outputs. For HTML outputs, you can style the elements with CSS (see Style with CSS).

To learn how to add tasks to your topics, see Create a Task.

Create a Task

Use task elements to create a more formal structure for step-by-step procedures, where there is a task title as well as the procedure. You can also add other task-related elements.

To create a task:

Create a new topic or edit an existing one by selecting it in the Content Manager.

Alternatively, you can create or edit an informaltopic (see Create an Informal Topic).
In the topic, position the cursor so that it is at a valid position for a task element. This is similar to other types of list, where the cursor has to be between block elements, for example, after a para element but before the next para element.
Use the element context menu to add a task element.

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

Paligo adds a task element. It has a title element and a procedure element with a step inside it.
Enter the text for the task title and the procedure steps. To add another step, press Enter at the end of the currently selected step.

You can also add other elements, for example, you might want to add a para element for some text between the task title and the procedure. To do this, place the cursor at the end of the title and press Enter. You can then use the element context menu to add other elements.
To add a tasksummary element, position the cursor so that it is inside the task structure, between two block elements. Then use the element context menu to add a tasksummary element.

If the tasksummary element is not available in the element context menu, the cursor is not in the correct position.
Select inside the tasksummary element, and then use the element context menu to add elements. This could be one or more para elements for text, or you could add other types of content structure such as itemizedlist for a bullet list. Enter the content for the summary in the elements.
To add prerequisites, position the cursor so that it is inside the task structure, between two block elements. Then use the element context menu to add a taskprerequisites element.

Paligo adds a taskprerequisites element, and inside that there is a para element. Enter text in the para. You can also use the element context menu to add other elements inside the taskprerequisites element, such as an itemizedlist.
To add taskrelated elements, position the cursor so that it is inside the task structure, between two block elements. Then use the element context menu to add a taskrelated element.
Select inside the taskrelated element. Then use the element context menu to add other types of content structure, such as para elements or an itemizedlist. Typically, you would use these to add text and you can then add links by using the Insert > Link menu in the toolbar.
Check the box Use gateway to enable IP Allowlisting. Optional

Note

The tasksummary, taskprerequisites, and taskrelated elements are all optional. You can also add other types of content structure inside a task, such as an example. The element context menu provides access to those elements that are valid at the cursor's current location.

Here, we have covered the elements that are only available for use in a task.

Task Example

In this example, we'll guide you through the steps for creating a task in an informaltopic. The task will have a task summary, prerequisites, and related tasks. You will learn how to add the various task elements and then you can apply the same techniques when creating your own tasks.

Example 35. Create a task that has a task summary, prerequisites and related tasks

Create an informaltopic. You could use a regular topic instead if you prefer. The informaltopic has a para element inside it by default. That's not needed for the task, so delete the para element.
Next, use the element context menu to add a task element.

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

When you add the task element, Paligo adds a task, and a title and a procedure inside the task element.
Enter the text for the title.
Position the cursor after the task's title element but before the next element (procedure, in this case). Then use the element context menu to add the tasksummary element.
Select the tasksummary element and then use the element context menu to add an element for your summary content. There are many different types of element that you could use here, as explained in the DocBook schema, see DocBook task summary.

For this example, use the para element and enter your summary text in that.
For prerequisites, place the cursor after the tasksummary but still inside the task element. In the element structure menu, you should see that task is the last element shown.

Then use the element context menu to add the taskprerequisite element.
Select the taskprerequisite element and use the element context menu to add the elements you want to use. There are many possibilities here, including different types of list and paragraph elements too.

For this example, add a paragraph with the text "Prerequisites" followed by an itemized list. Add the prerequisites as list items.
Enter the text for your procedure steps. Press Enter at the end of a step to create the next step in the procedure, or you can manually add a step and a para element for each one if you prefer.
For related tasks, add the taskrelated element. For this example, add it after the procedure and use it to add links to other related tasks. Then select the taskrelated element and use the element context menu to add the elements for a paragraph and an itemized list. Insert links to other topics as list items.

Select Save.

You should now have a complete and valid task. In the underlying code, which you can see in the source code editor, the task should look something like this:

<?xml version="1.0"?>
<sidebar xmlns="http://docbook.org/ns/docbook" xmlns:xinfo="http://ns.expertinfo.se/cms/xmlns/1.0" xml:id="UUID-9fa6db45-2e2d-09b6-11f5-2bda3215f17b" version="5.0" xml:lang="en" xinfo:resource="UUID-9fa6db45-2e2d-09b6-11f5-2bda3215f17b" xinfo:resource-id="110111" xinfo:resource-type="component" xinfo:resource-subtype="informaltopic" xinfo:resource-title="Replace ACME 100 Battery" xinfo:resource-titlelabel="" xinfo:version-major="1" xinfo:version-minor="0">
  <task>
    <title xinfo:text="110123">Replace ACME 100 battery</title>
    <tasksummary>
      <para xinfo:text="110124">How to replace the battery in an ACME 100 device.</para>
    </tasksummary>
    <taskprerequisites>
      <para xinfo:text="110125">Prerequisites:</para>
      <itemizedlist>
        <listitem>
          <para xinfo:text="110126">ACME 100 replacement battery</para>
        </listitem>
        <listitem>
          <para xinfo:text="110127">ACME 100 unit key</para>
        </listitem>
      </itemizedlist>
    </taskprerequisites>
    <procedure xml:id="procedure-idm4679030963721632366065195995">
      <step>
        <para xinfo:text="110128">Use the ACME 100 unit key to unlock the 4 corner locks on the rear panel of the ACME 100. Turn the key anticlockwise to unlock.</para>
      </step>
      <step>
        <para xinfo:text="110129">Press the release latch and then gently pull the cover towards you.</para>
      </step>
      <step>
        <para xinfo:text="110130">Remove the battery from the ACME 100 device.</para>
      </step>
      <step>
        <para xinfo:text="110131">Insert the replacement battery, making sure that the positive and negative terminals of the battery are positioned correctly. The battery compartment has plus (positive) and minus (negative) markings to show the appropriate connections.</para>
      </step>
      <step>
        <para xinfo:text="110132">Close the hatch and make sure the latch clicks into place.</para>
      </step>
      <step>
        <para xinfo:text="110133">Use the ACME 100 unit key to lock the corner locks.</para>
      </step>
    </procedure>
    <taskrelated>
      <para xinfo:text="110152">See also:</para>
      <itemizedlist>
        <listitem>
          <para xinfo:text="110153">
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://RANDOM">Recharge ACME 100 battery</link>
          </para>
        </listitem>
        <listitem>
          <para xinfo:text="110154">
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://RANDOM">Mains power for ACME 100</link>
          </para>
        </listitem>
      </itemizedlist>
    </taskrelated>
  </task>
</sidebar>

Note

The XML ids will be different in your topic.

Checklists

Use the checklists feature to add a list of checkboxes to your HTML5 help center, Zendesk, or PDF publications. The checklists work differently, depending on the type of publication.

In this article, we explain:

How the checklists work in the different types of output, see Checklists in HTML5 Help Center and Zendesk and Checklists in PDF.
How to create checklists, see Create a Checklist.
How to set up your checklist so that it is pre-checked in PDF outputs, see Create a Checklist.

Note

Checklists are only supported when publishing to PDF, HTML5 help centers, and Zendesk. They are not supported when publishing to other types of output, including other types of HTML.

Checklists in HTML5 Help Center and Zendesk

In HTML5 and Zendesk publications, each list item has a container with a clickable checkbox and a close option that removes the step from view.

Example of checklist in HTML5 help center output. Each list item has a checkbox and a close icon. There is also a refresh icon to reset the list. The checkox, close icon, and refresh icon are numbered 1, 2, 3 with callouts for illustration purposes only.

Where (1) is the clickable checkbox, (2) is the close option, and (3) is the refresh option. The refresh option returns the list to its original state, with all boxes unchecked and every checkbox in the list made visible.

The following video shows how checkboxes are presented in HTML5 help centers and Zendesk.

To find out how to make your own checklists, see Create a Checklist.

Note

Make sure that your checklist has an xml:id attribute and value for the itemizedlist root element. It will only work properly if it has an id. To find out how to generate an id, see IDs for Cross-References. You can also use the Editor Settings to set Paligo to generate ids for all lists automatically.
This feature uses JavaScript that, in some browsers like Safari, will only run if published on a web server. So if you test it locally, you may need to try another browser first. But once published, it will work on all modern browsers.
If you are publishing to Zendesk, make sure that in Zendesk's Guide Admin settings, the Display unsafe content option is turned on. The HTML tags needed for checklists are not included in Zendesk's list of "safe tags".

Checklists in PDF

In PDF publications, checklists appear as a list with a checkbox for each item. The checkbox is clear by default, so that if your readers print out the PDF, they can physically check the boxes as they complete each item. But if you prefer, you can set the boxes to be pre-checked, which can be a good idea if you only want to indicate a checklist symbolically.

To find out how to create a checklist and pre-set the checkboxes for PDF, see Create a Checklist.

Create a Checklist

Use the checklist toolbar to create a checklist in a topic.

The toolbar in the Paligo editor. A callout arrow points to the checklist icon, which is a checkbox.

When you select the checklist toolbar icon, Paligo adds the first item in a checklist. You can add text to that item and when you press Enter at the end, it will automatically create the next checklist item. The checklist is actually an itemizedlist with a role attribute of checklist. So you could also make one by adding an itemized list (i.e. bullet list or undordered list) and giving it a role attribute with checklist as the value.

The paligo editor showing a topic that has a checklist. The element structure menu shows the section > itemizedlist structure. The Element attributes section shows that the itemizedlist element has a role attribute with a value of checklist

To set the list to have pre-checked checkboxes for PDF outputs, select the itemizedlist element in the element structure menu. Then add the value checked to the role attribute. Use a semicolon as a separator, for example:

Element attributes panel showing the itemizedlist element has role set to checklist; checked. It also has an xml:id attribute.

A checklist would usually be on the first level only, but it is possible to have nested checklists too. Each checklist item can also contain any other content just like a regular list, such as images, other lists, tables, etc. For these, add the block element, such as a list, inside the listitem.

To end the list, position the cursor outside the the itemizedlist and then you can add another block element, such as a para. This approach is common to all lists.

You can then add extra content after your checklist, if needed. Save your topic when you have finished.

Note

The checklist functionality only works if the itemizedlist element for the checklist has an xml:id. To find out if it does, select the itemizedlist element in the element structure menu and then look at the element atttibutes.

Paligo editor shows the itemizedlist element is selected. In the element attributes, it has an xml:id.

If there is an xml:id with a value, the list is fine. If there is no xml:id, you can add one. To do this, we recommend that you select itemizedlist in the elementstructure menu, then select the Generate id option.

Question and Answer Lists (FAQs)

With question and answer lists, you can provide your readers with answers to popular questions, all in one topic. These are useful for FAQ-style topics (Frequently Answered Questions).

Tip

If there are a high number of questions and answers, it can make your FAQ difficult for readers to use. For this reason, it is a good idea to limit your FAQs to popular questions only, and cover more specific questions elsewhere in your content.

Of course, you could take that approach to all of your "customer questions" and make sure they are answered in your regular content. Then there may be no need for an FAQ at all.

Create a Question and Answer List (FAQs)

To create a topic containing a question and answer list (FAQs):

Create a new topic or edit an existing one by selecting it in the Content Manager.
In the topic, use the element context menu to add the qandaset element. This is the "container" element for all of your questions and answers.

When you add a qandaset element, Paligo automatically adds some of the "child" elements that it needs for your questions and answers.

The structure is:
```
 <qandaset>
    <qandaentry>
      <question>
        <para><?placeholder Insert text?></para>
      </question>
      <answer>
        <para><?placeholder Insert text?></para>
      </answer>
    </qandaentry>
  </qandaset>
```
The important things to note here are that:
- The qandaset is the "container" element for all of the questions and answers
- Each question and answer pair go inside a qandaentry element
- Each question consists of a question element and a para element inside it. You add your text inside the para element.
- Each answer consists of an answer element and a para element inside it. You add your text inside the para element.
Enter your text for the question and the answer.
To add another question and answer in the same list, you need to position the cursor carefully. It has to be below the answer and at the position where qandaset is the last element shown on the element structure menu.
Use the element context menu to add the qandaentry element.

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

Paligo adds an extra question and answer pair.

Note

If the element context menu does not allow you to search and find the qandaentry element, it is because the cursor is not in the correct position. Go back to step 4 and make sure that the cursor is in the correct place.
Repeat steps 3-5 inclusive to add all of the questions and answers for your list.
Select any part of the list and then select the qandaset element in the element structure menu.
In the Element attributes section, add the defaultlabel element and set its value to either:
- none
  
  The questions and answers will have no prefix. The question text is bold and the answer is regular text.
- number
  
  The questions are numbered.
- qanda
  
  The questions have a Q: prefix and the answers have an A: prefix.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish your topic, the list will appear as a question and answer list. The questions will use the formatting that you set for the defaultlabel attribute.

Tip

When publishing to HTML5, Paligo adds a list of links before the Q and As. The links have the same text as the questions.

Add the below code string at the end of the layout CSS to:

Hide the links before the Q and As.
Add a space between the Q and A labels and the text.
Add spaces between the Q and As.

/* Styling for Q&A sets*/
div.qandaset ul
{display:none;  /* hides links Q-title */
}
div.qandaset
{margin-bottom:15px; /* space between Q&A set */
}
div.qandaset tr td p
{margin-bottom:5px; /* space between Q & A rows */
}
div.qandaset tr td:first-child 
{padding-right:5px; /* space after labels (e.g. "Q:")*/
}

Control Numbering on Question and Answer Lists (FAQs)

By default, question and answer lists (FAQs) are numbered, as defined in DocBook XML. If you prefer, you can set your question and answer lists to have no numbering or to use Q: and A: prefixes instead.

To control the numbering:

Edit the topic that contains the qandaset list. Select any part of the list and then select the qandaset element in the element structure menu.
Use the Element attributes section to give it the defaultlabel attribute, and set the value of the attribute:
- none
  
  The questions and answers will have no prefix. The question text is bold and the answer is regular text.
- number
  
  The questions are numbered.
- qanda
  
  The questions have a Q: prefix and the answers have an A: prefix.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish the topic, the qanda list will use the formatting you have selected.

Add Sections and Titles to Question and Answer Lists (FAQs)

If you have lots of questions and answers, you may want to group them into different categories rather than have one long list. To do this, use the qandadiv element.

Note

If you decide to use qandadiv sections, you need to use them for all of your questions. You cannot have a mix of some questions inside a qandadiv and some not (this is because it is not supported by the content model).

To add sections and titles in your question and answer lists:

Create a Question and Answer List (FAQs).

Your qandaset list should have a structure where qandaset is a parent element, with qandaentry as a child. Your questions and answers should be children of the qandaentry.

Note

In this procedure, we explain how to add qandadiv sections to an existing qandaset. But if you are creating a qandaset from scratch, you can insert the qandadivs as you go along instead.
Select any part of the question and answer list and then select the qandaset element in the element structure menu. Then select Go to element from the menu.
Use the element context menu to add the qandadiv element inside the qandaset element.

To access the element context menu, press Alt and Enter (Windows) or Option ⌥ and Enter (Mac).

If the qandadiv option is not available in the list, then the cursor is in the wrong position. Go back to the previous step and make sure you have selected the qandaset element.

When you add a qandadiv element, you can add a range of other elements inside it, as well as the qandaentry elements. Typically, you will want to use a title inside the quandadiv to give the section a heading, and then you can also add other elements if needed, such as a para.

Paligo's element context menu provides a list of the elements that are valid at the currently selected position. To find out more about the individual elements, refer to the Supported Attributes.
Use the XML tree view to drag and drop the elements you want to be inside the qandadiv part of your list. Your qandaentry elements need to be inside a qandadiv, as well as any additional elements you want inside the qandadiv, such as a title and para.

Note

When using qandadiv elements, all qandaentry questions and answers need to be inside a qandadiv.
Repeat steps 2-4 for any further qandadivs.
Check the box Use gateway to enable IP Allowlisting. Optional

When you publish the topic, it will look something like this (HTML version shown):

Where you get:

A list of all the qanda sections and the questions in those sections
Sections of questions, where each section is a qandadiv element. In the image shown, the sections also have titles.
A list of the questions in that section
The questions and answers in that section

For PDF outputs, you do not get the extra lists, only the sections and the questions and answers.

Note

To set numbering or letting for the questions and answers, see Control Numbering on Question and Answer Lists (FAQs). To control the numbering and/or styling of the qandadivs and their lists, use CSS. For PDFs, a customization may be required, please contact customer support for details.

Example 36. Sample topic showing valid XML structure for qandaset that uses qandadiv elements

The following XML shows valid structure for a qandaset that uses qandadivs, each with a title and a single question and answer. Note that we have removed the XML ids from the code. If you use the source code editor and then copy and paste this into a Paligo topic , when you save it, Paligo will generate the XML ids automatically.

In the structure, note that every question and answer is inside a qandaentry. Each quandaentry is inside a qandadiv, and all of the qanda-related elements are inside the qandaset element, which acts as a "container".

<?xml version="1.0"?>
<section>
  <title>ACME 100 Troubleshooting</title>
  <para>This article provides answers to some of the most common questions about ACME 100. To find an answer, go to the section that relates to your type of problem and then look to see if your question has been answered.</para>
    <qandadiv>
      <title>Battery Troubleshooting</title>
      <qandaentry>
        <question>
          <para>How long is the battery life?</para>
        </question>
        <answer>
          <para>With normal use, the battery should last around 10 hours before it needs recharging.</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>When will I need to replace the battery?</para>
        </question>
        <answer>
          <para>Typically, batteries last around 2 years with normal usage.</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>How do I get a replacement battery?</para>
        </question>
        <answer>
          <para>Batteries and chargers are available on our website.</para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv>
      <title>Controls Troubleshooting</title>
      <qandaentry>
        <question>
          <para>How do I change the temperature controls?</para>
        </question>
        <answer>
          <para>Go to Controls &gt; Temp &gt; Limits to change the temperature limits for the automatic temperature controls. For manual temperature controls, go to Controls &gt; Temp &gt; Manual.</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>How do I control the vents?</para>
        </question>
        <answer>
          <para>Go to Controls &gt; Vents &gt; to open or close the vents. Note that you cannot control the vents if they are set to be automatically controlled (see Auto &gt; Vents).</para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv>
      <title>Monitor Troubleshooting</title>
      <qandaentry>
        <question>
          <para>How do I monitor the temperature differences over a day?</para>
        </question>
        <answer>
          <para>Go to Dashboard &gt; Temp to view the temperature charts. You can set the charts for 1 day, 1 week, 1 month, or 1 year of data.</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>How do I monitor the effects of cooling?</para>
        </question>
        <answer>
          <para>Go to Dashboard &gt; Cooling to view the cooling charts. You can set the charts for 1 day, 1 week, 1 month, or 1 year of data.</para>
        </answer>
      </qandaentry>
    </qandadiv>
  </qandaset>
</section>

Variable List (Description List)

A variable list is a list where each entry has one or more terms and a description. They have many potential uses, but are often used for explanations of technical terms or jargon. When published, they are shown in rows and columns, so they look like a borderless table, but they do not have the underlying structure of a table. For HTML outputs, they use description list HTML tags (<dl>, <dt> and <dd>).

Example of a variable list in PDF output.

Note

Variable lists have no relation to variable sets or variable content. The term variable list comes from the DocBook specification, where variablelist is the name of the element for this type of list.

To find out about variable sets and variable content, see Variables.

Create a Variable List

The variablelist element is a "container" for all of your terms and descriptions.

 <variablelist>
    <title></title>
    <varlistentry>
      <term></term>
      <listitem>
        <para></para>
      </listitem>
    </varlistentry>
  </variablelist>

The variablelist has a title. This is optional and if you do not want it, you can remove it and the variablelist will still be valid.
Each term(s) and description pair go inside a varlistentry element
Each term consists of a term element. You add the term text directly inside this element, there is no para.
Each description consists of a listitem element and a para element inside it. You add your description text inside the para element.

To create a variable list (description list):

Create a new topic or edit an existing one by selecting it in the Content Manager.
Position the cursor where the variable list is to be inserted.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter variablelist and select it from the menu.

Paligo automatically adds a title for the variable list, one term and one description.
Enter a text for the title (or remove it).
Enter a text for the term and listitem (its description).
Position the cursor at the end of the description and press Enter to add another term.

Paligo adds another pair (term and description) to the list.
To end the list, position the cursor after the variablelist.

From this position, you can, if needed, use the element context menu to add additional content.
Select Save.

Articles in this section

Types of Lists

Other Available List Types

Create a List or Procedure

Tip

Tip

Convert a List

Set Starting Number

Select Numeration Type

Move a List Item or Step

Split a List

Merge Two Lists

Convert a List into Paragraphs

Convert a Group of Paragraphs into a List

Note

Reuse Content in Lists

Add Content Inside a List Item or Step

Note

Optional and Required Steps in Procedures

Note

Note

Sublists

Create an Indented Sublist

Convert a Sublist into a Different Type of List

Convert a Sublist into Items in the Main List

Outdent a Sublist

Tasks

Note

Create a Task

Note

Task Example

Note

Checklists

Note

Checklists in HTML5 Help Center and Zendesk

Note

Checklists in PDF

Create a Checklist

Note

Question and Answer Lists (FAQs)

Tip

Create a Question and Answer List (FAQs)

Note

Tip

Control Numbering on Question and Answer Lists (FAQs)

Add Sections and Titles to Question and Answer Lists (FAQs)

Note

Note

Note

Note

Variable List (Description List)

Note

Create a Variable List

Related articles