Eric Cressey

Tech writer - Content strategist - Developer

Adding In-Page Navigation to Long Topics

| Comments

People scan help pages. If a page doesn’t look like it contains the right information, people will abandon it and look elsewhere. If you want your topics to be useful, make it immediately clear what they contain and put the most useful information at the top. If you can, keep them short. Short topics are easy to scan and usually fit on the screen without scrolling.

Sometimes you’ll write long topics. Naturally, these topics are harder to scan. They cover more material and often contain several layers of information that might not be immediately clear when the page loads. However, you can create in-page navigation links to make these pages much easier to scan and use. Here’s an example from Microsoft’s help.

Notice the box that says “In this article.” It tells the user what’s in the topic and allows him to jump to a particular section. Imagine how unwieldy this topic would be without that box. That’s what I’m going to show you how to add to your Flare output.

Rather than manually adding these navigation boxes to long topics, let’s get JavaScript and CSS to do the work for us. Now, when a topic loads, JavaScript will check to see if there is more than one heading on the page and, if there is, it’ll create a navigation box so users can quickly jump to the other headings. In addition, it’ll also create “To the top” links to allow users to jump back to the top of the page from any of those headings.

Save the following code as a JavaScript file in your web help project.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

$(document).ready(function(){

    var topic = $(':header').not(':first');
    if (topic.length > 0) {
        $('<div class="sidebar"><span class="sidebarheading">In this topic</span><div class="sidebartoc"><ul class="innerstep"></ul></div></div>').insertBefore('h1');

        $(topic).each(function () {
            var topicName = $(this).text(); //get the name that will be displayed in the nav box
            var linkName = topicName.replace(/\s/g, ''); //edit the name for use as an anchor
            $('<a name="' + linkName + '"></a>').prependTo(this); //puts an anchor with a name attribute we created by the topic so we can link to it
            $('<li><a class="topiclink navlinks" href="#' + linkName + '">' + topicName + '</a></li>').appendTo('ul.innerstep'); //nests the subheading under its heading in the navigation box
        })

        for (var i = 0; i < topic.length; i++) {
            $('<div><a href="#" class="totop">To the top</a></div>').insertBefore(topic[i]); //add to the top button to links on page.
        }
    }
});

Add this JavaScript file to your master page

  1. Open your project in MadCap Flare. Open your target’s master page.
  2. Place your cursor under the topic body proxy.
  3. Click Insert on the ribbon. In the Symbols section, click Script. The Insert Script dialog box will open.
  4. Next to Language, select text/javascript.
  5. Next to Script Link, click Browse and open the script file you created earlier.
  6. Click OK to insert the script on your master page. Remember to save the file.

Add the CSS styles for this navigation box to your CSS file

  1. In the Content Explorer, browse to and select the CSS file for your target.
  2. Right-click the CSS file and open it with the text editor of your choice.
  3. Insert the following CSS rules below all of your other rules. Remember to save the file.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

div.sidebar {
    background-color: #f0f0f0;
    color: #f7f7f7;
    display: block;
    float: right;
    font: normal 14px Arial;
    line-height: 19px;
    margin: 0px 0px 15px 15px;
    padding: 12px 0 0 0;
    width: 190px;
    outline: 10px solid white;
    border: 1px solid #e0e0e0;
}
.sidebarheading {
    margin-left:15px;
    color: #0C4380;
    display: inline;
    font: bold 16px Arial;
    height: auto;
    line-height: 24px;
    width: auto;
}

div.sidebartoc {
    color: #f7f7f7;
    display: block;
    font: normal 13px Arial;
    line-height: 19px;
    padding: 7px 0px 19px 0px ;
    width: 190px;
}

a.navlinks {
    cursor: pointer;
    color: #555;
    letter-spacing: normal;
    font-weight: normal;
    font-style: normal;
    font-family: Arial, sans-serif;
    text-decoration: none;
}

a.navlinks:hover {
    text-decoration: underline;
}

div.sidebartoc li, div.sidebartoc ul {
    padding-right: 0px;
    margin-top: 0px;
    padding-left: 0px;
    margin-left: 0px;
    list-style: none;
    margin-bottom: 0px;
}

.totop {
    float:right;
    font: bold 11px Arial;
    text-decoration: none;
}
.totop:hover {
    text-decoration: underline;
}

.sidebartoc ul li a {
    padding:5px 15px;
    display: block;
    line-height: 19px;
}

.topiclink {
    line-height: 12px;
    padding:0px 20px;
    display: block;
}

Build your web help and enjoy the in-page navigation! If you have questions or want to know how to customize this solution, let me know in the comments!

Comments