Skip to main content
All CollectionsIntegrationsCMS & Deployment
How to Integrate Marker.io with Sphinx Documentation Using ReadTheDocs Theme
How to Integrate Marker.io with Sphinx Documentation Using ReadTheDocs Theme

Embedding Marker.io in Sphinx Docs for Issue Reporting

Joe Scanlon avatar
Written by Joe Scanlon
Updated over a week ago

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:

  1. Navigate to Your Sphinx Project Directory:

    • Open your project folder where your Sphinx documentation is stored.

  2. Create a New Directory for Templates:

    • If it doesn't already exist, create a _templates folder 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:

  1. Create or Edit the Layout Template:

    • In the _templates directory, create a file named layout.html. If it already exists, you can edit it.

  2. 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:

  1. Open the conf.py File:

    • This file is located in the root of your Sphinx project.

  2. Update the Template Path:

    • Add or modify the templates_path variable to include the _templates directory:

      templates_path = ['_templates']

Step 4: Build Your Documentation

Objective: Generate the HTML version of your documentation with the integrated Marker.io widget.

Instructions:

  1. 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:

  1. Open the Generated HTML Files:

    • Navigate to the _build/html directory, where the HTML files are stored.

  2. 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.py and 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.

Did this answer your question?