Apidoc: Showing sub-titles of the header and footer in the navigation panel

[YannDoW]

Currently, the only way to create static content (unless you are willing to change the template) is to add a header and a footer files in markdown format. OK. I'll use the header file to write a (long) introduction about our API, and I'll use the footer to list descriptions of all the objects that our API can return.

Here is my feature request: it would really be great to see the sub-titles of these markdown files be listed in the navigation panel on the left. For example, my footer file looks like this:

========

User
----

bla bla bla about user data

Achievement
-----------

bla bla bla about Achievement data

It would be great to see on the left panel the "User" and the "Achievement" as links, so that people could go easily to them - and the rest of the doc could reference links to them.

Thanks for your attention, keep up the great work!

Yann

[crebuh]

+1 would be very great

e.g. I use the header template to give an overview (with 7 sections) of the API and it would be nice to have these sections/subheadings also als clickable sections in the sidebar

[AlexMcArrow]

+1 give me too

[YannDoW]

OK, I really needed it so I wrote a little bit of JS. It's clean enough to be shared and be adapted by whoever is interested. Here is goes.

1) Create a file called apidoc_nav.js and put the following code in it:

/**
 * Add navigation items by analyzing the HTML content and searching for h2 tags
 * @param nav Object the navigation array
 * @param content string the compiled HTML content
 * @param index where to insert items: either 1 or nav.length
 */
function add_nav(nav, content, index) {
    if (!content)   return;
    var topics = content.match(/<h2>(.+?)<\/h2>/gi);
    topics.forEach(function(entry) {
        var title = entry.replace(/<.+?>/g, '');    // Remove all HTML tags for the title
        var entry_tags = entry.match(/id="(?:api-)?([^\-]+)-(.+)"/);    // Find the group and name in the id property
        var group = (entry_tags ? entry_tags[1] : null);
        var name = (entry_tags ? entry_tags[2] : null);
        if (title && group && name)    {
            nav.splice(index, 0, {
                group: group,
                name: name,
                isHeader: false,
                title: title,
                isFixed: false,
                version: '1.0'
            });
            index++;
        }
    });
}

/**
 * Add navigation items for the header and the footer
 * @param nav Object the navigation array
 * @param apiProject Object the apiProject data
 */
function add_header_footer_nav(nav, apiProject)
{
    if (apiProject.header) {
        add_nav(nav, apiProject.header.content, 1);
    }
    if (apiProject.footer && apiProject.footer.title != null) {
        add_nav(nav, apiProject.footer.content, nav.length);
    }
}

2) In the main.js file, insert the following code around line 220:

    // Add Header and Footer navigation sub-titles
    add_header_footer_nav(nav, apiProject);

3) In the index.html file, call the apidoc_nav.js just before the call to main.js:

<script src="apidoc_nav.js"></script>  <!-- Add this -->
<script data-main="main.js" src="vendor/require.min.js"></script>

What does it do? The code will parse your header and footer files, and search for <h2> tags. If it can extract an id from it with a name that follows the api-group-something format, it will create an entry in the navigation bar. So all you have to do is to create level-2 titles and use a bit of HTML to stick an ìd` in it.

Examples:

Here we use a <span> tag after the ##markdown tag. The "group" is intro and the rest is start-well:

## <span id="api-intro-start-well">Starting Well with APIDoc</span>

Same example, using the alternate ----- markdown tag for level 2 titles:

<span id="api-intro-start-well">Starting Well with APIDoc</span>
----------------------------------------------------------

Remember that it is important to have your id start by api-, then have another word (the group), a dash and a name (which can contain dashes, that's OK).

After that, in the rest of your documentation, you can easily point to these entries using regular markdown:

Learn [how to start well with APIDoc](#api-intro-start-well)

Enjoy!

[NicolasCARPi]

Closing as user provided a solution.