-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Showing sub-titles of the header and footer in the navigation panel #321
Comments
+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 |
+1 give me too |
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.
/**
* 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);
}
}
// Add Header and Footer navigation sub-titles
add_header_footer_nav(nav, apiProject);
<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 Examples:Here we use a
Same example, using the alternate
Remember that it is important to have your After that, in the rest of your documentation, you can easily point to these entries using regular markdown:
Enjoy! |
…on panel All level-2 titles located in the header and the footer files and that have an id in the /api-group-something/ format will get an entry in the navigation bar. 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> ---------------------------------------------------------------- Same example, using HTML instead of Markdown: <h2 id="api-intro-start-well">Starting Well with APIDoc</h2> 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)
… entries in the navigation panel Level 1 titles that have an id like api-something will create a top entry in the navigation panel. This allows the creation of multiple top-level entries in the header and footer documents. Example: <span id="api-introduction">Introduction to APIDoc</span> ============================================= Note that if such titles are found, they will replace the titles set in the apidoc.json.
Closing as user provided a solution. |
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:
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
The text was updated successfully, but these errors were encountered: