This article helps you to troubleshoot the malfunctioning of the TOC in Wiki articles.

As reported in the in some cases the TOC is not working or gets corrupted.

Below you'll find some hints and tips to repair the TOC.
Feel free to add more tips & tricks!

How the TOC Works

When a Wiki article has the [toc] tag, scripts are triggered to create a Table of Contents from the headings in the article. In the Wiki editor you create headings by highlighting the line and selecting one of the heading paragraph styles, such as Heading 1, or Heading 2. When an article that has the [toc] tag is saved, a script runs to make sure each heading line has a named anchor tag. If the heading already has a valid named anchor tag, it is left alone. Otherwise, the script creates an anchor tag whose name is equal to the text of the heading, but with spaces and other special characters replaced by underscores. When the article is displayed (or printed) another script runs to create a Table of Contents from the heading lines. The text of the heading is used for the entry in the Table of Contents, but the named anchor tag actually links the entry to the correct heading in the article.

Problem 1: Zeros in Heading Named Anchor Tag

Unfortunately, the [toc] scripts have a bug. Zero characters, "0", can appear in heading lines, but if there are any zeros in the corresponding named anchor tag, the tag is not recognized for the Table of Contents. When the article is saved, the script that runs ignores any named anchor tags with "0"s. Instead, another named anchor tag is created from the heading text. Unfortunately, the new anchor tag name still has the "0" character. When the script runs to display (or print) the article, any headings with "0"s in the named anchor tag are ignored and not included in the Table of Contents.

Example of Heading with No Problem

Following is an example line that you might want to make a heading in a Wiki article:

How the TOC Works

After you highlight this line in the Design editor and select paragraph style "Heading 1", the line will appear as follows in the HTML editor:

<h1>How the TOC Works</h1>

The heading is enclosed by the <h1> and </h1> tags. Other tags, such as <style> and </style> tags, might appear, but you can ignore them. If the article includes the [toc] tag, then after you save the HTML for this line will appear as follows:

<h1><a name="How_the_TOC_Works"></a>How the TOC Works</h1>

The [toc] script has added the named anchor tag, which is enclosed by the <a name> and </a> tags. When the article is displayed, the entry "How the TOC Works" will appear in the Table of Contents and link to this heading.

Example of Heading with Zero Character in Named Anchor Tag

If your heading is "Windows Server 2012", the resulting HTML can appear similar to below:

<h1><a name="Windows_Server_2012"></a><a name="Windows_Server_2012"></a><a name="Windows_Server_2012"></a>Windows Server 2012</h1>

Notice that the named anchor tag is repeated three times. This probably means the article has been saved three times. Each time the [toc] script did not recognize the anchor tag name and recreated the problem tag again. However, the heading does not appear in the Table of Contents. You can fix this in the HTML editor by modifying the line so it appears as follows (for example):

<h1><a name="Windows_Server_TwentyTwelve"></a>Windows Server 2012</h1>

You can replace the "0" character with anything, as long as the anchor tag name is unique in the Wiki article.

Problem 2: Foreign Characters in Heading Named Anchor Tag

The same problem as described above can happen if the heading includes foreign (non-English) characters. So far the following characters behave just like the zero character:

é í ç ã

There are probably other characters that cause the problem. As with the zero character, these foreign characters cause the anchor tag name to not be recognized. The anchor name tags get repeated every time the article is saved, and the heading is not included in the Table of Contents. The fix is to replace these characters in the <a name> tag in the HTML editor with something else.

Update July 8, 2013. It appears that all foreign language characters can cause this problem. See this article for details:

WiKi: Tip - How to Add Table of Contents to the Article in Foreign Language

Problem 3: Duplicate Heading Named Anchor Tags

Named anchor tags in the Wiki article should be unique. However, when a heading line is copied in an article, then modified to create a new heading, the text of the new heading will be correct, but the named anchor tag might be identical to the original. You can only see this in the HTML editor. When there are heading lines with duplicate named anchor tags, all the corresponding entries in the Table of Contents will link to the first heading with the name.

Example of HTML With Duplicate Named Anchor Tags

Duplicates can also appear without copying heading lines. For example, a Wiki article might appear similar to below in the HTML editor, with duplicate heading lines resulting in duplicated named anchor tags:

<h1><a name="Example_1"></a>Example 1</h1>
<p>This is example number 1</h>
<h2><a name="Design"></a>Design</h2>
<p>The design for example number 1 is ...</p>
<h2><a name="Troubleshooting"></a>Troubleshooting</h2>
<p>Troubleshooting steps for example 1 are ...</p>
<h1><a name="Example_2"></a>Example 2</h1>
<p>This is example number 2</h>
<h2><a name="Design"></a>Design</h2>
<p>The design for example number 2 is ...</p>
<h2><a name="Troubleshooting"></a>Troubleshooting</h2>
<p>Troubleshooting steps for example 2 are ...</p>

Notice that the names "Design" and "Troubleshooting" (highlighted in the example above) are repeated. All six of the example headings will appear in the Table of Contents, but both of the entries for "Design" will link to the first heading line with this name. Both entries for "Troubleshooting" will link to the first heading with this name. Such problems can be very hard to spot, but can confuse readers. Users will link to the wrong section and not realize it. This is why it can be important to test the Table of Contents to make sure each entry actually links where you expect.

Example of HTML With Duplicate Named Anchor Tags Fixed

The fix in this example is to modify the names in the HTML to make them unique. For example:

<h1><a name="Example_1"></a>Example 1</h1>
<p>This is example number 1</h>
<h2><a name="Ex1_Design"></a>Design</h2>
<p>The design for example number 1 is ...</p>
<h2><a name="Ex1_Troubleshooting"></a>Troubleshooting</h2>
<p>Troubleshooting steps for example 1 are ...</p>
<h1><a name="Example_2"></a>Example 2</h1>
<p>This is example number 2</h>
<h2><a name="Ex2_Design"></a>Design</h2>
<p>The design for example number 2 is ...</p>
<h2><a name="Ex2_Troubleshooting"></a>Troubleshooting</h2>
<p>Troubleshooting steps for example 2 are ...</p>

The duplicate names (highlighted above) have been modified by adding a short string to make them unique. The Table of Contents will now work correctly.

Leading Digits in Heading Lines are Ignored When the <a name> Tag is Created

Even though the header line text may be unique in the Wiki article, be aware that leading digits in the text are ignored when the <a name> tag is created. For example, if your article has the heading line "1.3 References", and later the heading line "3.3 References", the automatically generated <a name> tags will be identical. You must fix this in the HTML editor.

Troubleshooting

Remove All Zeros From Anchor Tags in the Headers

If you use a zero anywhere in the header, the Table of Contents may not work. Find the header in the HTML editor and check the <a name> tag. All zeros in the named anchor tag must be removed or changed to something else. Make sure the name is unique in the article.

Remove Foreign Characters From the Headers

If you use foreign (non-English) characters in the header, the Table of Contents may not work. Find the header in the HTML editor and check the <a name> tag. All foreign characters in the named anchor tag must be removed or changed to something else. Make sure the name is unique in the article.

Check the Header Tags in HTML

The HTML can be very difficult to read and work with. You can search for header lines by using the Find button (the button with the binocular icon) in the HTML editor and search for the string "<h". Ignore any "<hr /> tags (horizontal rules). Edit the anchor tag names so there are no zero characters. For example, replace this line in the HTML editor:

<h1><a name="Windows_Server_2012"></a>Windows Server 2012</h1>

with something like this:

<h1><a name="Windows_Server_2Oh12"></a>Windows Server 2012</h1>

The character "0" has been replaced by the character string "Oh" in the anchor tag name.

HTML Code Cleaning

Carefully Check if All HTML Tags Match Correctly.

Go into HTML edit mode and check the HTML tags.
You could also copy the code into an HTML editor to check it off-line using the tool.

Hint:

Authoring Blog and Wiki Content with Expression Web

This is a pretty intensive and time consuming job, but make sure all tags have opening and closing tags (if applicable).

Following tags are important root causes for troubled layout:

table tags not correctly closed
- The <tr> element defines a table row. There must be a matching closing table row tag </tr>.
- The <th> element defines a table header. Make sure there is a matching </th> tag.
- The <td> element defines a table cell. There must be a matching </td> tag.
- A more complex HTML table may also include <caption>, <col>, <colgroup>, <thead>, < tfoot>, and <tbody> elements.
bullet lists (yes, like this one)
- check for <ul> and <li> tags that are not closed correctly with </ul> and </li> tags.
<p> paragraph tags must be closed with matching </p> tags.
header tags (<h1>, <h2>, ...) must have matching closing tags (</h1>, </h3>, ...).
<div> tags require closing </div> tags.
hard returns, line splits, ...

Copy Valid Headers (Replace Faulty Headers) Rebuild Headers

If you don't find the cause right away, a quick fix is to copy/past an existing well-behaving header.

Just a hint:

Copy the header after the last normal text section, before the faulty header.
Make sure the anchor tag name is unique in the article.
Save the article first and check the TOC, before you remove the faulty header.

Test the TOC

Even if all of the headers appear correctly in the TOC, it may not work. As a final check, you may need to test the finished Wiki article to make sure that each entry in the Table of Contents links to the correct location in the article. This is especially necessary of there are duplicate headings in the article. If any entry in the TOC does not link to the correct location, you probably have duplicate anchor tag names.

Caution

It is also possible that another article (or even the same article) links to a heading in the Wiki article. When you modify the <a name> tag, you may break the link in the other article. Unfortunately, it is impossible to check for this. However, if any link in an article fails, check the address in the <href> tag in the HTML, then make sure the corresponding <a name> tag in the other article matches.

Article Optimization

Maximize OOB Wiki Layout

The online Wiki editor has some interesting layout, out-of-the-box.
Limit the initial layout of your article. First make sure your article has content with basic layout.
Then later on, add some fancy stuff.

Hint: