Adding Custom Menu Items to Your Documentation Site Header (ReadtheDocs theme)

by

A well-organized and accessible documentation site is a cornerstone of user experience. It’s not just about presenting information but also about navigation and ease of access. Among the essential elements, the header stands out as a prime spot to include crucial links and menus for swift navigation. If you’re using the ReadTheDocs theme and seeking to amplify your site’s header with custom menu items, you’re in the right place.

If using Restructured Text and Sphinx infrastructure, you can dynamically inject custom HTML elements into your documentation site’s header upon page load. This script provides a seamless way to incorporate additional menu items into the header.

JavaScript for Custom Headers

document.addEventListener('DOMContentLoaded', function () {
    var customHeaderCode = `
        <div class="header">
            <div class="header-right">
                <a href="http://docs.titaniamlabs.com/index.html">Documentation Home</a>
                <div class="dropdown">
                    <button class="dropbtn">Related Documents
                        <i class="fa fa-caret-down"></i>
                    </button>
                    <div class="dropdown-content">
                        <a href="https://docs.titaniamlabs.com/trail/getting_started/index.html">Trail Getting Started</a>
                        <a href="https://docs.titaniamlabs.com/trail/getting_started/faqs.html#faqs">FAQs</a>
                    </div>
                </div>
            </div>
        </div>
    `;

    // Create a new div element to hold the custom header code
    var customHeaderDiv = document.createElement('div');
    customHeaderDiv.innerHTML = customHeaderCode;

    // Insert the custom header code at the beginning of the document's body
    document.body.insertBefore(customHeaderDiv, document.body.firstChild);
});

This script allows you to define a custom HTML structure containing the desired menu items. The customHeaderCode variable encapsulates the HTML structure for the header with specific links and dropdowns you wish to include. It’s designed to be easily modifiable, enabling you to adjust links, dropdowns, and styling to suit your documentation site’s needs.

How to Use this Script

  1. Store this javascript in your _static/js folder in your Restructured Text source folder.
  2. Build the doc site using the Sphinx infrastructure.

Code Explanation

  1. Event Listener: The script listens for the DOMContentLoaded event, ensuring the entire DOM (Document Object Model) has loaded before executing the code. This ensures that the header modifications occur seamlessly without hindering the page load process.
  2. Custom Header Code: The customHeaderCode variable holds the HTML markup for your custom header. It includes various elements like anchor tags (<a>) for links and a dropdown menu for related documents.
  3. Creating and Inserting Elements: Using JavaScript, a new div element (customHeaderDiv) is created to contain the custom header code. This code is then inserted at the beginning of the document.body, ensuring it appears at the top of the page.

By employing this script, you can dynamically augment your ReadTheDocs theme-based documentation site’s header with additional menu items, allowing users to navigate effortlessly between various sections and related documents.

Remember, customization is key to tailoring the header to your specific requirements. You can modify the HTML structure and links within the customHeaderCode variable to align with your documentation site’s structure and content.

Have fun customizing your documentation site’s header to elevate your users’ browsing experience!

Leave a Comment