Skip to main content

Index Topic

Abstract

Learn how to set up an index topic.

Paligo has several index-related elements that you can use to Create an Index Topic and Add Index References to your topics. Add the index topic to your publication the same way as you would add any other topic to a publication. Typically, it is placed at the end of the publication.

These are especially useful in PDF outputs, where users are more likely to need to refer to an index to find out where certain subjects are explained in a document.

With HTML and other outputs that will be read digitally, the index is often less useful as there is a search tool to use instead. However, you may still decide to include an index in your online content too.

A PDF output showing an index with many index entries. They are ordered into 3 equal sized columns.

Tip

Paligo can generate and sort your index automatically, Index Sorting for Language Symbols

Create an Index Topic

Abstract

Learn how to create an index in Paligo. The index will contain a list of terms with a reference to the relevant parts of the content.

An index topic is a regular topic where an index element has been added. When you add the index topic to your publication, Paligo will automatically gather all index references from the topics. The index references will be categorized by letter and sorted alphabetically and each has a page reference or a link.

If the publication does not contain any index references, the index will be empty. You need to add index references to your topics before you publish, see Add Index References.

Consider how you want your index to appear in the published output:

  • The index used as a main topic. This is the most common approach for an index.

  • The index used as a subsection inside a main topic (for example References).

A topic with a title set to "Index" and below that, it contains an index element.
A References topic that contains an index. The index has its own title, which is "Index"

To the left - The index as a main topic. To the right - The index as a subsection.

Note

The index element will automatically add a title named Index. This means that if you have a main topic called Index, the subsection will also be called Index. This extra title can be hidden, see Hide Index Title for HTML5 Output or Activate Index Auto-Title for PDF.

Tip

To find out more about using the Element Context Menu to add content, see About Authoring

To create an index topic:

  1. Create a new topic.

  2. Position the cursor at a valid position for the index element.

    For example, after the section title, but before the first para element.

    Index topic with cursor positioned below the title but above the first paragraph.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter index and select it in the menu.

  5. Delete the para element that is included by default, if not needed.

  6. Select Save. Save icon.

  7. Add your index topic to your publication, see Add Content to a Publication.

When you publish your publication, Paligo will automatically gather the index references.

Add Index References

Abstract

Learn how to add index references to your topics in Paligo. The references tell Paligo what terms should appear in the index and what type of reference should be used.

To get index entries to appear when you Create an Index Topic, you need to markup the topics with index references. These references tell Paligo what terms should appear in the index topic and what type of reference should be used. If your content does not contain any index references, your index topic will be empty when you publish. There are four types of index references that you can use depending on which information to be included in the index topic.

Appearance

Type

Description
Index for letter T, showing Temperature with a page number, Thermal image with a page number, and Thresholds with a page number.

Primary Index References

The index topic will only show the main terms in alphabetical order with page numbers. Learn more, see Add a Primary Index Reference.
Index for letter T. It shows Temperature and a page number at the top level. Indented at the second level are entries for Alarms, Maximum, Minimum, and Shutdown, each with a page number.

Secondary Index References

The index topic will show both main terms and subterms in alphabetical order with page numbers. Learn more, see Add a Secondary Index Reference.
Index for letter T. It has an entry for Thermal and next to that it shows see Temperature.

See Index References

The index topic will show the main terms in alphabetical order without page numbers with a link within brackets to another term. Might be that you want to include terms that could be used for the same thing and refer the reader to the proper term instead. Learn more about how to add these extra references, see Add a See Index Reference.
Index for the letter T. It has an entry for Temperature with two page numbers as references. Below that, there is an entry for Thermal, next to it is the text: see Temperature.

See Also Index References

The index topic will show the main terms in alphabetical order with page numbers including a link within brackets to an additional term. Learn more about how to add these extra references, see Add a See Also Index Reference.

Note

If you publish to HTML or HTML5 there will be hyperlinks instead of page numbers.

Add a Primary Index Reference

If you use a primary index reference, the index topic will only show the main terms in alphabetical order with page numbers. If you publish to HTML, there is a hyperlink to the page instead of a page number.

Index for letter T, showing Temperature with a page number, Thermal image with a page number, and Thresholds with a page number.

The index topic will look like this with primary index references.

Tip

To find out more about using the Element Context Menu to add content, see About Authoring.

To add a primary index reference to your content:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor immediately before the text for the term that you want to use.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter indexterm and select it from the menu.

    Paligo adds an indexterm element with an primary element inside it.

  5. Enter the main term inside the primary element to make it appear in the index.

    Paligo editor shows a para element that contains an indexentry element. Inside the indexentry element is a primary element.

    Note

    You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr

  6. Select Save. Save icon.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a Secondary Index Reference

If you use a secondary index reference, the index topic will show both main terms and subterms in alphabetical order with page numbers. If you publish to HTML, there is a hyperlink to the page instead of a page number.

Index for letter T. It shows Temperature and a page number at the top level. Indented at the second level are entries for Alarms, Maximum, Minimum, and Shutdown, each with a page number.

The index topic will look like this with secondary index references.

Tip

To find out more about using the Element Context Menu to add content, see About Authoring.

To add a secondary index reference to your content:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor immediately before the text for the term that you want to use.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter indexterm and select it from the menu.

    Paligo adds an indexterm element with an primary element inside it.

  5. Enter the main term inside the primary element to make it appear in the index.

    Paligo editor shows a para element that contains an indexentry element. Inside the indexentry element is a primary element.

    Note

    You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr

  6. Position the cursor after the primary reference, but before the end of the indexterm.

    Add_Secondary_Reference.jpg

    Tip

    Move the cursor with the keyboard arrows to easier position it between the chevrons.

  7. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  8. Enter secondary and select it from the menu.

  9. Enter the subterm inside the secondary element to make it appear in the index.

    Paligo editor shows a para that contains an indexentry element. Inside the indexentry element there is a primary element with the main term. After the primary element is a secondary element.

    Note

    You should now have a structure like this (where we have used "alarm" as an example of a secondary term):

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</primary><secondary>alarm</secondary></indexterm>temperature alarm.</para>

  10. Select Save. Save icon.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a See Index Reference

If you use a see index reference, the index topic will show the main terms in alphabetical order without page numbers with a link within brackets to another term. Might be that you want to include terms that could be used for the same thing and refer the reader to the proper term instead.

A see index reference is a combination of a primary element for the main term and a see element for the link to the additional term.

Index for letter T. It has an entry for Thermal and next to that it shows see Temperature.

The index topic will look like this with see index references.

Note

It is also possible to use a see element for a secondary term, but these entries can become complicated. It is usually better to keep your index entries as simple as possible, so that your readers can find the information they need quickly.

To add a see index reference:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor immediately before the text for the term that you want to use.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter indexterm and select it from the menu.

    Paligo adds an indexterm element with an primary element inside it.

  5. Enter the main term inside the primary element to make it appear in the index.

    Paligo editor shows a para element that contains an indexentry element. Inside the indexentry element is a primary element.

    Note

    You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr

  6. Position the cursor after the primary reference, but before the end of the indexterm.

    Add_Secondary_Reference.jpg

    Tip

    Move the cursor with the keyboard arrows to easier position it between the chevrons.

  7. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  8. Enter see and select it from the menu.

  9. Enter the term inside the see element that is to appear as link within brackets in the index.

    The entered term must be an existing index term.

    Paligo editor shows a para that contains an indexterm element. Inside the indexterm element is a primary element with a main term. There is also a see element.

    Note

    You should now have a structure like that shown below, where we have used "Temperature" as the "see" index entry.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Thermal</primary><see>Temperature</see></indexterm>temperature alarm.</para>

  10. Select Save. Save icon.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Add a See Also Index Reference

If you use a see also index reference, the index topic will show the main terms in alphabetical order with page numbers including a link within brackets to an additional term. If you publish to HTML, there is a hyperlink to the page instead of a page number.

A see also index reference is a combination of a primary element for the main term and a seealso element for the link to the additional term.

Index for the letter T. It shows Temperature as an entry. It has two page numbers for references and also another reference that shows see also Thermal.

The index topic will look like this with see also index references.

Note

It is also possible to use a seealso element for a secondary term, but these entries can become complicated. It is usually better to keep your index entries as simple as possible, so that your readers can find the information they need quickly.

To add a see also index reference:

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor immediately before the text for the term that you want to use.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter indexterm and select it from the menu.

    Paligo adds an indexterm element with an primary element inside it.

  5. Enter the main term inside the primary element to make it appear in the index.

    Paligo editor shows a para element that contains an indexentry element. Inside the indexentry element is a primary element.

    Note

    You should now have a structure like that shown in the example below. Here, we have used "temperature" as an example of a primary term.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</pr

  6. Position the cursor after the primary reference, but before the end of the indexterm.

    Add_Secondary_Reference.jpg

    Tip

    Move the cursor with the keyboard arrows to easier position it between the chevrons.

  7. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  8. Enter seealso and select it from the menu.

  9. Enter the term inside the seealso element that is to appear as a link within brackets in the index.

    The entered term must be an existing index term.

    Paligo editor shows a para that contains an indexterm element. Inside the indexterm element is a primary element with a main term. There is also a see also element.

    Note

    You should now have a structure like that shown below, where we have used "Thermal" as the "seealso" index entry.

    <para>If the sensor detects that the room is too hot or too cold, the system will raise a <indexterm><primary>Temperature</primary><seealso>Thermal</seealso></indexterm>temperature alarm.</para>

  10. Select Save. Save icon.

When you publish, Paligo will automatically add your index entries to your index topic. If you do not have an index topic, see Create an Index Topic.

Index Sorting for Language Symbols

Paligo can currently only use UTF-8 to define the sort order in an index. This means that languages that use symbols or a mix of symbols and phonemic characters (like Japanese, Korean and Chinese) will encounter problems when publishing in multiple languages.

A possible workaround for PDF output is by defining an indexterm that uses a phonemic word (alphabetic writing) for index sorting. The indexterm is invisible in the topics and works in the background to sort and group the index references.

The sortas attribute on the primary, secondary and tertiary elements is used to express a key. Usually the key is the same word as used as the value of the primary, secondary and tertiary element. This key is subsequently used to look up the actual phonemic version of the term in a lookup file for the language being published to.

Index_with_language_symbols.jpg

The image above shows a possible Japanese index.

Enable Lookup Files for Index Sorting

For languages that require a mapping between a symbolic term and a phonemic sortas value, you have to enable the feature in the System settings. Also, you have to prepare one lookup file for each language that includes the sortas key and the translated phonemic word to replace it.

The sortas key will control the sort order of the element sortas attribute and group the indexterms in the index topic.

  1. Log in to Paligo via a user account that has administrator permissions.

  2. Select the avatar in the top-right corner. User avatar. It shows the user's image and their name. Next to the name is a downward pointing arrow, which when selected, reveals a menu.

  3. Select Settings from the menu. Cog icon.

  4. Select the System Settings tab. Cog icon.

    System_Settings_tab.jpg

  5. Enable Use lookup files for index sortering with the slider.

    Use_Lookup_files_for_index_sorting.jpg

  6. Prepare a lookup file for each language and name it like this: sortas-lookup-language code.xml.

    Replace the text "language code" with a two-letter or four-letter code (for example "sortas-lookup-ja.xml", "sortas-lookup-zh.xml" or "sortas-lookup-ko.xml". Learn more, see Language Codes.

  7. Build the file like this:

    <sortas-lookup lang="language code">
  <sortas key="phonemic word" value="phonemic word translated"/>
</sortas-lookup>
    Sortas-Lookup_file.jpg

    The image shows what a sortas-lookup file for Japanese could look like in an instance that uses English as source language.

  8. Upload the lookup file to the xsl folder, see WebDAV Access to your Paligo Instance Folders.

    Lookup-files_in_xsl-folder.jpg

Prepare Topics for Lookup files

Prepare the topics with indexterms that will be replaced with translated phonemic words from a file called sortas-lookup, see Enable Lookup Files for Index Sorting. Once the topics are ready, you add them to a publication containing an index topic and translate them.

The output index will be sorted according to the translated phonemic words (sortas keys) from the sortas-lookup files, but show the language symbols instead of the sortas attribute value.

Source_topic_for_lookup_file.jpg
Translated_topic_from_lookup_file.jpg

To the left - the English source topic. To the right - the translated topic shows the symbol instead of the phonemic word.

Note

When you have this feature enabled and Paligo cannot find a lookup file for a language, all sortas attributes for this language will automatically be removed during the publishing process.

This means that you only require lookup files for languages that use symbols or a mix of symbols and phonemic characters (like Japanese, Korean and Chinese), but not for languages that use the Latin alphabet (like Swedish and English).

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

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Position the cursor after the word that needs an indexterm added.

  3. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  4. Enter indexterm and select it from the menu.

  5. Enter the word (within the chevrons) to be shown in the index topic. (Probably a symbol, if your source language is Japanese.)

    It will be replaced with a translated phonemic version from the sortas-lookup file.

    Phonematic_Indexterm.jpg

    The indexterm is invisible in the topic and used for sorting and grouping the index.

  6. Select the primary element in the Element Structure Menu and choose Go to element.

    Indexterm_Go_to_element.jpg

    Note

    This also works for secondary and tertiary elements.

  7. Enter sortas in the Element Attributes Panel and select it from the menu.

    Sortas_Attribute.png

  8. Enter the key word that will fetch the phonemic word from the lookup file.

    The sortas key will control the sort order of the element sortas attribute and group the indexterms in the index topic. For a Japanese source language this can actually be the symbol.

  9. Select Save. Save icon.

Index Title

Abstract

Learn how to add a title element to an Index in Paligo. Typically, index titles are used when you what to give the index topic a different name than "Index".

When you Create an Index Topic the index element includes an extra title named Index. It is possible to hide this title for both PDF and HTML5 output or include them in PDF bookmarks.

index-traditional.jpg
index-inside-different-topic.jpg

To the left - the index as a main topic. To the right - the index as a subsection.

Activate Index Auto-Title for PDF

Paligo can automatically add a title to your index for PDF output. The automatic title will be "Index" and if you publish in other languages, a translation of "Index" is provided as well.

To include or exclude the automatically generated index title:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select General and choose Glossary, Index, and Bibliography.

  4. Control whether to include or exclude the Index auto-title.

    • Enabled - Paligo will check if your index has a title during publishing:

      • Existing title - Paligo will use that title.

      • No title - Paligo will generate a title element with "Index" as the title text.

    • Disabled Paligo will not generate an automatic index title. Default

  5. Select Save.

When you publish to PDF with this layout, the output will include or exclude an automatic index title.

Include Index Title in PDF Bookmarks

PDFs can have bookmarks that act like a table of contents in a side panel, where your topics are shown in order. If you have an index, it's likely that you will want a link to the index to appear here.

If your index is inside a topic called "Index", you will not need to take any action. The "Index" topic will appear in the bookmarks by default.

But if your index is inside a topic with a different title, there will be no obvious way for the reader to access the index. For example, let's say you have added your index to a topic called "references". In the published PDF, the bookmarks will only show "References", which makes it harder for your readers to find the index.

references-index.jpg

To fix this, you can set Paligo to include the index's title in the bookmarks as well. If your index does not have a title, you can add one or you can set Paligo to generate one automatically.

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select General and choose Glossary, Index, and Bibliography.

  4. Enable the Index title or auto title in bookmarks setting to get Paligo to include the title of the index element in the bookmarks.

    index-title-or-auto-title-bookmarks.jpg

    Note

    This setting will only work if your index has a title, or you have set Paligo to generate a title automatically.

  5. Select Save.

When you publish to PDF with this layout, Paligo includes the index title in the bookmarks. It is a subsection of its parent topic.

A PDF output that shows a references topic. There is an index inside the references topic. In the bookmarks sidebar, there is a link for the references topic, and at a lower level, a link for the index title.

Hide Index Title for HTML5 Output

Your HTML5 output will show your index title by default if your index:

  • Contains a title element

  • Has no title element, but your HTML5 layout is set to generate an index title automatically. The automatic title is called "Index" (or a translation of Index for other languages).

This can mean that your HTML index has two "Index" titles, one for the topic and one for the index element. To hide the title for the index element, use CSS:

  1. Create or edit an existing custom CSS file and add the following code:

    .index .titlepage{
    display: none;
}

    To learn more about creating custom CSS, see Style with CSS.

  2. Create an HTML5 Help Center layout. Alternatively, you can Edit a Layout.

  3. Upload your custom CSS to the HTML5 layout.

  4. Select Save.

When you publish to HTML5 using this layout, the index element's title is hidden.

Note

If you want to show the index title again, change the CSS to:

.index .titlepage{
    display: block;
}

Multi-Column Index

Abstract

How to set up multi-column index pages for PDF outputs.

By default, your index is shown as a single-column index in PDF outputs. This can be suitable for shorter indices.

If you prefer a multi-column layout to show more index entries per page and to adjust the gap between the columns, this is set in the Layout Editor.

A PDF output showing an index with many index entries. They are ordered into 3 equal sized columns.

A PDF output showing a three-column index

To define the index columns for PDF output:

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select General in the sidebar. New_Layout.jpg

    Select_General_PDF_small.jpg

  4. Select Glossary, Index and Bibliography.

  5. Select the Number of columns for the Index from the menu.

    You can choose from 1 to 4.

    Paligo will aim to balance the columns automatically, so that they are approximately equal length.

    Number_of_columns_Index_small.jpg

  6. Enter a width between each column in the Columns gap for the index. You must specify a measurement unit after the width (pt, px, em).

    This setting only applies if there is more than one column.

    Column_Gap_Index_small.jpg

  7. Select Save.

When you publish to PDF with this layout, your index will use the column number and spacing settings that you applied.

Search for Index References

Use the Advanced Search to find topics that include index references. Depending on what you want to find, you can choose to:

  • Include all topics with index references by using the indexterm element in the search.

  • Narrow down the search by specifying the type of index reference (primary, secondary, see or seealso).

To search for index references:

  1. Select Quick Search in the top menu. Search.png

    Close up of top part of Paligo user interface. A callout box highlights the search icon in the top-right corner.

  2. Select Advanced Search. Filter_symbol_small.png

    Quick search bar. There is a down arrow button, a quick search field, a search icon, and a funnel icon.

  3. Select the Search tab.

    Search_Tab.png

  4. Enter indexterm or specify a particular index reference type (primary , secondary, see or seealso) in the Contains field.

    Search_Index_References.jpg
    Search_Index_References_Seealso.jpg

    To the left search for content with the indexterm element. To the right search for content with the seealso element.

  5. Select the Content checkbox and clear the others in the Search in field.

  6. Select Search.

  7. All topics that match the search criteria will be presented below the search area.

    SearchResults_Index_References.jpg