Integrate Marker.io with Sphinx Documentation Using ReadTheDocs Theme

Integrating the Marker.io widget into your Sphinx-based documentation can greatly enhance the feedback process by allowing users to directly interact with your documentation pages. This guide provides a concise and clear path to embedding the Marker.io widget across all pages of your Sphinx documentation. We assume you are using the sphinx_rtd_theme, popular for its clean and professional appearance.

Step 1: Identify and Prepare the HTML Template

Goal: Prepare to modify the base HTML template to include the Marker.io widget.

Instructions:

Locate the Template: If you're using the sphinx_rtd_theme, the default layout file (layout.html) typically resides within the theme's template directory. Direct modifications to this file are not recommended, as updates to the theme could overwrite your changes.
Create a Custom Template Directory:
- Navigate to your Sphinx project directory.
- Create a new directory named _templates if it does not already exist:
```
mkdir _templates
```

Step 2: Customize the Base Template

Goal: Integrate the Marker.io JavaScript into a custom template to ensure it appears on every page.

Instructions:

Create a Custom Template File:
- Inside the _templates directory, create or edit a file named layout.html.
- Add the following content to extend the default layout and embed the Marker.io script:
```
{# _templates/layout.html #}
{% extends "!layout.html" %}

{% block footer %}
{{ super() }}

######
###### Marker.io snippet code goes here!
######
######

{% endblock %}
```
- This template code extends the existing layout.html file and injects the Marker.io script just before the end of the <footer> block, ensuring it loads on every page.

Step 3: Configure Sphinx to Use the Custom Template

Goal: Direct Sphinx to use your custom template for HTML generation.

Instructions:

Open your conf.py file located in the project root directory.
Add or update the templates_path variable to include _templates:
```
templates_path = ['_templates']
```

Step 4: Build Your Documentation

Goal: Generate your documentation with the integrated Marker.io widget.

Instructions:

From your Sphinx project directory, execute the following command:
```
make html
```

This command compiles the documentation into HTML, incorporating the Marker.io widget across all pages.

Step 5: Verify the Integration

Goal: Ensure the Marker.io widget is functioning correctly on all pages.

Instructions:

Navigate to the _build/html directory.
Open various HTML files in your browser to confirm that the Marker.io widget appears and functions as expected on each page.

Conclusion

By following these steps, you have successfully integrated the Marker.io widget into your Sphinx documentation, using the ReadTheDocs theme. This integration allows for seamless user interaction and feedback, enhancing the usability and effectiveness of your documentation.

Guided Widget Targeting with Marker.io

Understanding the Marker.io Feedback Page

How to Integrate Marker.io with Remix

Integrating Marker.io in a React Next.js 13+ Environment

Integrate Marker.io with SharePoint