The problem: Table of Content in Word exports

When exporting to Word using the default templates, you will see that the exported Word document contains the Description part of each exported Work item.

The export function works correctly, however, there is one issue with it. If the Description of a Work item contains a Heading 1/Heading 2/etc. markup, these headings will appear in the Table of Contents of the exported Word document, and also on the Navigation pane of Word document, as seen on the below screenshot.

To remove the additional heading items from the exported Word document, follow the instructions described in the next section.

The solution how-to

These Heading elements from the description of Work items are appearing in the Words' Table of Contents, because the HTML Heading elements are automatically mapped by Word's Heading 1/Heading 2/etc. styles, and these automatically appear in the TOC.

The fix is implemented in the attached custom template: download

The solution is:

• Create new Word styles for Heading1/Heading2/etc. which will not appear in the TOC
• During the Word export, capture the Heading elements in the generated HTML (built from the Wiki markup)
• rewrite the HTML markup and map to a new Word style which will not appear in the TOC
• Then adjust the CSS so the Heading elements will look same as the style in Word

Prepare a new template

First, create a new copy of the default template and save it. All changes here will be added into that.

Creating new Word styles for Heading elements that do not appear in TOC

Open your template and define a new style called HiddenHeading1 there. To do that follow the steps on this screenshot:

1. Click on the small icon in the Styles toolbar. This shows you the Styles dialog.
2. Click on the New icon on the Styles dialog, this opens up the Create new style dialog
3. On the Create New style dialog enter the new style name HiddenHeading1 in this example.
4. Then select the parent style (Style based on), which should be the Style where the new Style inherits its settings and look. This will be Heading1 in this case
5. Next customize the new Style's look. For that click on the [Format] button below, and select Paragraph
6. Next the Paragraphs' dialog appears. Because in our HiddenHeading1 we do not want this appearing in the TOC change the Outline level property to Body Text which will make that this Style will not appear in the TOC.

Now we have created a HiddenHeading1 which is a copy of Heading 1 , but that element with this style will not appear in the TOC. Repeat the same for Heading 2 and Heading 3 and create their similar pair like HiddenHeading2 and HiddenHeading3.

Rewrite the Heading Wiki/HTML elements of description

Now we have a HiddenHeading1/HiddenHeading2, etc. Word styles. To use these styles the instead of the standard Heading 1/etc. the Word export template needs to rewrite the HTML generated from the Work Items' description to use them.

So if the description contains this wiki text:

!1 Heading one

content-one

That is exported/rendered as this HTML fragment:

<h1>Heading one</h1>
content-one

To make this to use the HiddenHeading1 Word style we must replace such <h1> tags with this Word compatible markup:

<p class="HiddenHeading1">Heading one</p>
content-one

To perform this we must add some code which rewrites the HTML output in the Word export template. So use this script as replacement in the Description part of your custom Word export template:

## capture the HTML form of the Work item's description to a variable
#set($html = $wikiMarkupProcessor.transformToHtml(${describable.description}, ${describable.descriptionFormat}, false, false, $wikiContext))

<!-- ## Trick: adding an html comment block around this script to avoid any output appearing from here
## parse the HTML output of the item’s description using JSOUP
## calls the static method: JSoup.parse(String)
#set($Jsoup = $Class.forName(“org.jsoup.Jsoup”))
#set($doc = $Jsoup.parse($html))

##following modifies all h elements adds red font-color
##${doc.select(“h1,h2,h3,h4,h5,h6”).attr(“style”,”mso-outline-level:6;color:red;”)}
## replace H1 with <p class=”HiddenHeading1” so the Word’s HiddenHeading1 style will be applied on this,
## therefore won’t appear in the Table of contents!
${doc.select(“h1”).tagName(“p”).attr(“class”,”HiddenHeading1”)}
${doc.select(“h2”).tagName(“p”).attr(“class”,”HiddenHeading2”)}
${doc.select(“h3”).tagName(“p”).attr(“class”,”HiddenHeading3”)}
-->
## print out the modified HTML
${doc.html()}

What does this do? The comments inside of the script helps to understand, but in short:

• Calls the standard wiki->HTML conversion method and captures its HTML output to a variable
• Uses Jsoup java HTML parser library to parse the HTML. This library is shipped with codebeamer as default and we use it to clean up HTML elsewhere, but it is nicely usable here too.
• Using the Jsoup's selector-syntax look for H1/H2/H3 html tags, and using Jsoup's manipulation methods replace them with the appropriate <p> tags with the CSS classes set up correctly.
• Finally the modified HTML markup is printed out

Add CSS style for correct look and to bind with correct Word style

Now the h1/h2/h3 HTML/wiki headings are replaced with a paragraph, still this does not get the correct Word style and does not look good in the final Word document.

To get this corrected you will need to add some CSS style rules.To generate these missing CSS styles do this:

• Go to Word, create a new paragraph in your template for each new style, so there should be one paragraph with HiddenHeading1, and another one for HiddenHeading2, and so on.
• Save the template using the Save as feature of Word, and save as HTML format:
• Open the created style.htm in a plain text editor (notepad)
• In the style.html search for the CSS rules for HiddenHeading1 and the other new styles you need:
• The found custom style will contain an mso-style-name which binds this CSS style to the appropriate Word style. It also contains other look elements for example font's size and others.
• Copy all needed CSS rules to your template and add it to the Custom CSS block:

Now you are done. Save the template and try an export.

The final result will be:

• The Heading elements of an issue's description does not appear in the Words' Table of Contents
• But the remapped Heading elements will look the same as the normal Heading 1, etc. styles