Feedback widget for MkDocs

PushFeedback collects user feedback directly from your website. This guide covers installation in a MkDocs project.

Prerequisites

Before you begin, you need:

• A PushFeedback account. If you don't have one, sign up for free.
• A project created in your PushFeedback dashboard. If you haven't created one yet, follow the steps in the Quickstart guide.
• A MkDocs project.

Installation

Floating button

1. Navigate to your docs folder and locate the overrides directory (create one if it doesn't exist).

2. Inside the overrides directory, create or edit the file named base.html.

   info

   The file names of the templates to override and the block names you need to override might be different, depending on your theme. This example is specifically for the Material for MkDocs theme. Always refer to your theme's documentation or source templates to ensure accurate customization.

3. In this base.html, extend the base template and override the necessary sections. Here's what you should add:

   {% extends "base.html" %}
   
   {% block extrahead %}
   <!-- PushFeedback styles -->
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.css">
   
   <!-- PushFeedback script as ES6 module -->
   <script type="module" src="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.esm.js"></script>
   {% endblock %}
   
   {% block content %}
   {{ super() }}
   
   <!-- Feedback button -->
   <feedback-button project="<YOUR_PROJECT_ID>" button-position="bottom-right" modal-position="bottom-right" button-style="dark">Feedback</feedback-button>
   {% endblock %}

4. Ensure your mkdocs.yml points to the overrides directory:

   theme:
       name: 'material'
       custom_dir: 'docs/overrides'

5. Build your MkDocs project:

   mkdocs build

   Once it builds successfully, verify that the feedback button appears and functions correctly on your site.

Inline button

1. Load the widget in your overrides/base.html head block:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.css">
   <script type="module" src="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.esm.js"></script>

2. Place the button in your overrides/base.html content block or a page:

   <feedback-button project="<YOUR_PROJECT_ID>" button-position="default" modal-position="center" button-style="dark">Feedback</feedback-button>

Embedded form

1. Load the widget in your overrides/base.html head block:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.css">
   <script type="module" src="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.esm.js"></script>

2. Place the form in your overrides/base.html content block or a page:

   <feedback-modal project="<YOUR_PROJECT_ID>" embedded="true"></feedback-modal>

Like and dislike buttons

1. Load the widget in your overrides/base.html head block:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.css">
   <script type="module" src="https://cdn.jsdelivr.net/npm/pushfeedback/dist/pushfeedback/pushfeedback.esm.js"></script>

2. Place the rating controls in your overrides/base.html content block or a page:

   <p>Was this helpful?</p>
   <div class="pushfeedback-thumbs-row">
     <feedback-button project="<YOUR_PROJECT_ID>" rating="1" button-position="default" modal-position="center" button-style="default" custom-font="true">
       <span class="pushfeedback-thumb-label">Helpful</span>
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3" /></svg>
     </feedback-button>
     <feedback-button project="<YOUR_PROJECT_ID>" rating="0" button-position="default" modal-position="center" button-style="default" custom-font="true">
       <span class="pushfeedback-thumb-label">Not helpful</span>
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 15v4a3 3 0 0 0 3 3l4-9V2H5.72a2 2 0 0 0-2 1.7l-1.38 9a2 2 0 0 0 2 2.3zm7-13h2.67A2.31 2.31 0 0 1 22 4v7a2.31 2.31 0 0 1-2.33 2H17" /></svg>
     </feedback-button>
   </div>

Clicking a rating opens the form with that rating selected; it does not submit until the visitor sends it.

Next steps

Choose what to do next:

• Customization — Adjust the widget's layout, styles, and text.
• Integrations — Forward feedback to Slack, email, Jira, and more.