In MadCap Flare 2017 r2, a handy option was added to the target file to synchronize navigation elements with table of contents (TOC) entries for HTML5 Top Navigation and skinless outputs.  At first, it may be hard to visualize what this feature is and why you might consider using it, so I’ll explain.

You may have an instance where a single topic needs to be linked to more than one node in your TOC.

In HTML5 Top Navigation output, certain navigation elements—such as breadcrumbs, side menu items, and mini-TOCs—are dynamically generated and displayed when a topic is selected from the table of contents.  Without the ability to synchronize these navigation elements with the TOC nodes, those menu items may display one instance of that topic in the TOC, when another instance may be preferred.

Here is a quick visual - I have a topic called Recycling Procedures that is linked in three places in my TOC:

flare nav elements 01

I will build my HTML5 Top Navigation target without enabling the option to synchronize.  When I look at my TOC, I can see Recycling Procedures under each top level menu.  So far, so good:

flare nav elements 02

When I select Recycling Procedures from the Keyboard menu in the TOC, the content looks great.  However, my breadcrumb trail doesn’t sync up, and it displays the third instance of where the topic is located in the TOC, under Mouse.  This is the default behavior.  The last instance of the topic in the TOC will be shown in the breadcrumb trail, not the one that was selected:

flare nav elements 03

To sync everything up, I can go into my target, and in the Advanced tab, choose Synchronize Navigation Elements with TOC Entries.

flare nav elements 04

After a rebuild, I select Recycling Procedures from the Keyboard menu item again.  Now my breadcrumb trail syncs up properly:

flare nav elements 05

This quick checkmark box seems like a no brainer, and will work for some authors.  It’s really easy to enable, and it keeps everything in sync when you have topics that live in multiple places in the TOC.

There are a couple of things to consider with this approach:

For one, you will notice that the URL paths for your topics are longer.  Without the synchronization, a URL for a topic looks like this:

OutputPath/HTML5/Content/Recycling.htm

With the synchronization, the same topic path looks like this:

OutputPath/HTML5/Content/Recycling.htm?tocpath=Keyboard%7C_____2

Another thing to consider is your search results.  Since there is only one source topic, there is only one topic in the output.  This means your search result will find the correct topic, but the dynamic content in the topic will display as it would have been opened from the last node of the TOC.

An Alternative Approach

If you decide you don’t like this option for your Top Navigation outputs, but you still want to have a topic live in more than one place in your TOC, there is another approach.

You can create a snippet that holds all the content for the topic.  Then you create as many “shell” topics you need to link to multiple places in the TOC, and insert the snippet into each one.  By using a snippet, you can achieve the same result, have shorter URLs, and utilize the power of snippet conditions should the need for additional single-sourcing power arise.

Here is an example of what that looks like in Flare:

flare nav elements 06

When I build, my output has the breadcrumb navigation properly synchronized:

flare nav elements 07

This approach offers some additional benefits:

  • Shorter URL: The option in the target to synchronize doesn’t need to be selected, so if the longer URL is bothersome, this method is a great option.
  • Ability to control topics found in search: Since we have individual shell topics, the search results can be controlled. For example, you can disable searching in all but one of those shell topics; otherwise, they will all show up in the search results. To disable search for a topic, right click on the topic and choose Properties. Click the Topic Properties tab, and uncheck the box labeled Include topic when full-text search database is generated. Your topic will be included in the output, however it will be excluded from search.
  • Dynamically generated navigation elements: Since each shell topic is an individual topic in the output, things like breadcrumbs and side menus are appropriately synchronized.
  • More granular control over content: Additional single sourcing power, like snippet conditions, can be utilized to customize the content of the snippet. In my example, I included the specialized procedures for each device into the snippet, and applied conditional tags. That way, when I insert the snippet into each shell topic, I can exclude the procedures that don’t apply to the device, at the snippet block level.  I don’t have to maintain three different snippets.

Here is a closer look at my snippet that is providing the content for the Recycling Procedures topic above:

flare nav elements 08

When I insert this snippet into the topic that will live under the Keyboard menu item, I can turn off the green and red conditions at the snippet block level, which will hide the content for the Monitor and Mouse recycling procedures. Here is what my shell topic looks like with the snippet inserted, and those snippet conditions applied:

flare nav elements 09

I want to point out that using snippet conditions may not be necessary at all. I used it in my example to show the extra single sourcing power available if this approach is used.

If you have a need to have the same topic live in multiple places in your TOC for your Top Navigation outputs, now you have some choices when it comes to ensuring your navigation elements like breadcrumbs, and side menus are in sync.  Have you tried one of these approaches yet? If so, feel free to share which one works best for you.