Indexing Terms with Macro

Index terms identify text which should be used for the generation of an index. By default, index terms are created from page labels. However, the Scroll Exporters also come with the {Index-term}-macro, which allows you to more granular specify the location of the index term within a page and to define primary, secondary and tertiary index terms.

In the following sections we describe how to mark index terms in your documentation using the {Index-term}-macro. 

Step 1 - Setup the index in the export template

Following the steps will allow you to add a basic, un-styled index page.

1. Create a *.vm file named keyword-index.vm and add the following code:

   CODE

   #macro(hmltIndexterm $terms $level)
   <ul>
       #foreach($term in $terms)
           #set($thisFirstChar = $term.KeywordString.substring(0,1))
           #if($level == 1 && $indexHelper.requiresNewSection($currentFirstChar, $thisFirstChar))
               #set($currentFirstChar = $thisFirstChar)
               <li class="index-terms-section-label">$stringEscapeUtils.escapeHtml($indexHelper.normalize($thisFirstChar))</li>
           #end
           <li>$stringEscapeUtils.escapeHtml($term.KeywordString)
               #set($topics = $term.SortedTopics)
               #foreach($topic in $topics)
                   <a class="index-term-link" href="${topic.createLink()}">link</a>#if($velocityCount < $topics.size()),#end
               #end
               #set($newLevel = $level + 1)
               #hmltIndexterm($term.NestedKeywords, $newLevel)
           </li>
       #end
   </ul>
   #end
   
   <div class="index-terms-container">
       #set($indexHelper = $context.getExportEventHandlerMap().get("indexHelper"))
   #set($currentFirstChar = "")
   #set($startLevel = 1)
   #hmltIndexterm($indexHelper.NestedKeywords, $startLevel)
   </div>

2. Within the Scroll WebHelp Theme template;
   1. add the keyword-index.vm to the scroll-html directory (/K15t-scroll-webhelp-theme-a61717c96039/src/main/resources/com/k15t/scroll/scroll-webhelp-theme/scroll-html)

   2. within the atlassian-plugin.xml file add the following code (after line 128):

      CODE

        <resource type="static-resource"    name="index.html"                                  location="com/k15t/scroll/scroll-webhelp-theme/scroll-html/keyword-index.vm">
                  <param name="needsRendering">true</param>
              </resource>

   3. save the changes in the atlassian-plugin.xml
3. Build the template (see Creating a Template) and upload to Confluence

Step 2 - Use the Scroll Indexterm macro

Following the steps below will allow you to define index terms that will be displayed in the index file within the export.

1. Click in front of the term you want to index.
2. Enter {scroll indexterm and press Enter.
   The screen Insert 'Scroll Indexterm' Macro is displayed.
3. Enter the primary index term in the field Primary.
   You must at least define the primary parameter.
4. Optional, you can add a secondary and tertiary index term in the field Secondary, respectively Tertiary.
5. Optional, enter a title of the keyword to be displayed in the index in the field Title.
   If your export content as context-sensitive help, this title will be displayed in a list, when multiple link targets for a keyword are available.
6. Optional, define the significance of the index term.

7. Click Insert.

You have now successfully indexed the wanted terms. In your exports the macro will insert the defined terms in your index.