TOC Menu Fails to Collapse When Hosting _build/html on Webserver

Introduction

When building documentation using Sphinx and deploying the _build/html on a webserver, users may encounter an issue where the table of contents (TOC) menu remains expanded and does not collapse when expected. This article aims to provide a solution to this problem.

Cause of the Issue

The TOC menu collapse functionality is implemented using JavaScript. When the _build/html is hosted on a webserver, the base URL of the page changes from the local file system to the server’s address. As a result, the JavaScript code that handles the TOC collapse fails to execute correctly.

Solution

To resolve this issue, we need to modify the JavaScript code to accommodate the change in base URL. The following steps outline the solution:

  1. Edit layout.html:

Open the layout.html file located in the _templates directory within the Sphinx source code.

  1. Find the TOC JavaScript:

Search for the following code within the <head> section of layout.html:

<script src="{{ pathto('_static/navtree.js', 1) }}" defer></script>
  1. Append the Base URL:

Add the following line below the existing script tag, replacing YOUR_BASE_URL with the actual base URL of your website:

<script>
    window.base_url = 'YOUR_BASE_URL';
</script>
  1. Save and Rebuild:

Save the layout.html file and rebuild the documentation using Sphinx.

Example:

If your website’s base URL is https://example.com/docs/, the modified layout.html will include the following code:

<script src="{{ pathto('_static/navtree.js', 1) }}" defer></script>
<script>
    window.base_url = 'https://example.com/docs/';
</script>

Verification

After rebuilding the documentation and deploying it on the webserver, refresh the page. The TOC menu should now collapse properly.

Conclusion

By appending the base URL to the JavaScript code, the TOC collapse functionality is restored when the documentation is hosted on a webserver. This modification ensures a seamless user experience and allows the TOC menu to behave as intended.

Related Posts
How to Fix WordPress\’s White Screen of Death issue

Don\'t be alarmed if you get a WordPress error message or a white screen. Someone has most certainly seen the Read more

Interfaces in PHP OOP

How do Interfaces work in PHP? Interfaces let you tell a class what methods it should have. Interfaces make it Read more

How to Find Wi-Fi network password in Windows 11, Windows 10, Windows 8, Windows 7

If you have another Windows PC already connected to your Wi-Fi network, you can use it to find the password Read more

coderazaa IFSC Code

What exactly is an IFSC code? The Indian Financial System Code (IFSC) is an 11-digit alphanumeric code that uniquely identifies Read more

RTE income limit 2024-25

Welcome to our site phponline.in. We\'ve provided you a lot of material today, and we\'d already given you a heads-up Read more

What is a Facebook Pixel Code? How do you get one? How do I add a Pixel Code it to website?

This guide will walk you through the steps of generating or locating your Facebook pixel code and integrating it into Read more

CSS Introduction

CSS: The Art of Styling Web Pages Cascading Style Sheets (CSS) is a powerful language that allows you to control Read more

Copy data from one MS Access database to another

Copy Data from One MS Access Database to Another In Microsoft Access, it's often necessary to transfer data between databases. Read more

Scroll to Top