This guide will walk you through embedding the Marker.io widget into your Sphinx-based documentation, specifically when using the sphinx_rtd_theme. This integration allows users to report issues directly from your documentation pages.
Step 1: Set Up a Custom Template Directory
Objective: Prepare to modify the base HTML template to include the Marker.io widget without directly editing the theme's files.
Instructions:
Navigate to Your Sphinx Project Directory:
Open your project folder where your Sphinx documentation is stored.
Create a New Directory for Templates:
If it doesn't already exist, create a
_templatesfolder to hold your custom layout files:mkdir _templates
Step 2: Customize the Base Template
Objective: Integrate the Marker.io JavaScript widget into the template to display it on all documentation pages.
Instructions:
Create or Edit the Layout Template:
In the
_templatesdirectory, create a file namedlayout.html. If it already exists, you can edit it.
Insert the Marker.io Widget Code:
Add the following content to extend the default layout and inject the Marker.io widget:
{# _templates/layout.html #}
{% extends "!layout.html" %}
{% block footer %}
{{ super() }}
<!-- Marker.io snippet code goes here -->
{% endblock %}
This code ensures that the Marker.io widget is added to the footer of every documentation page.
Step 3: Configure Sphinx to Use the Custom Template
Objective: Tell Sphinx to apply your custom template when building the HTML documentation.
Instructions:
Open the
conf.pyFile:This file is located in the root of your Sphinx project.
Update the Template Path:
Add or modify the
templates_pathvariable to include the_templatesdirectory:templates_path = ['_templates']
Step 4: Build Your Documentation
Objective: Generate the HTML version of your documentation with the integrated Marker.io widget.
Instructions:
Run the Build Command:
From the root of your Sphinx project directory, execute the following command:
make html
This command compiles your documentation into HTML, including the Marker.io widget across all pages.
Step 5: Verify the Integration
Objective: Confirm that the Marker.io widget is functioning correctly on every page.
Instructions:
Open the Generated HTML Files:
Navigate to the
_build/htmldirectory, where the HTML files are stored.
Test the Pages:
Open several of the generated HTML files in a web browser and check that the Marker.io widget appears and works as expected.
Additional Tips:
Keep a Backup: Before making any changes, consider creating a backup of your original
conf.pyand any template files.Widget Configuration: If needed, you can customize the Marker.io widget settings (like project assignment) directly in the snippet code.
Need Help?
If you have any questions, comments, or corrections, chat with us at the bottom right of our web pages.