Comments for VitePress and MkDocs documentation sites without a GitHub login

window.EchoThread.bootstrap() is the method the widget exposes for single-page hosts. It tears down the previous instance and mounts into whatever #echothread is on the page now.

Step 2: fill the doc-after slot

Create or edit .vitepress/theme/index.js (or .ts):

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import Comments from './Comments.vue'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'doc-after': () => h(Comments),
    })
  },
}

Run vitepress build and every page with the doc layout has a comment section after the content and before the footer. If you would rather have it above the previous/next links, use doc-footer-before instead; the slot list is in the VitePress guide linked above.

Turning comments off for one page

The component already respects comments: false in a page's front matter, so the API reference pages that should stay quiet only need:

---
comments: false
---

MkDocs

MkDocs themes are Jinja templates, and the supported way to change one is custom_dir: "Any file in the custom_dir with the same name as a file in the parent theme will replace the file of the same name in the parent theme" (Customizing your theme, read on 3 September 2026). Instead of replacing a whole file, you extend the base template and override one block.

Plain MkDocs, or any theme with a content block

In mkdocs.yml:

site_url: https://docs.example.com/
theme:
  name: mkdocs
  custom_dir: overrides

site_url matters: MkDocs builds page.canonical_url, "the full, canonical URL to the current page", from it (MkDocs theme developer guide, read on 3 September 2026). Then create overrides/main.html:

{% extends "base.html" %}

{% block content %}
  {{ super() }}

  {% if page.meta.comments %}
  <div id="echothread"
       data-api-key="YOUR_API_KEY"
       data-page-url="{{ page.canonical_url }}"
       data-identifier="{{ page.url }}"
       data-page-title="{{ page.title }}"></div>
  <script src="https://cdn.echothread.io/widget.js" async></script>
  {% endif %}
{% endblock %}

{{ super() }} keeps the theme's own content and appends yours after it. page.url is the page's path relative to the site root, stable as long as you do not move the file. The page.meta.comments guard makes comments opt-in per page:

---
comments: true
---

Drop the {% if %} if you want every page to have comments.

MkDocs does full page loads, so there is no navigation handling to add. The snippet is the same static markup you would put on any HTML page.

Material for MkDocs

Material ships an empty partial for exactly this purpose. Its guide says "The comments.html partial (empty by default) is the best place to add the snippet", and enables comments per page with the comments: true front-matter property (Adding a comment system, read on 3 September 2026). The same guide documents giscus and lists installing the Giscus GitHub App as the first step, which is the requirement this post exists to avoid.

With custom_dir: overrides set as above, create overrides/partials/comments.html:

{% if page.meta.comments %}
<h2 id="__comments">Comments</h2>
<div id="echothread"
     data-api-key="YOUR_API_KEY"
     data-page-url="{{ page.canonical_url }}"
     data-identifier="{{ page.url }}"
     data-page-title="{{ page.title }}"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>
{% endif %}

Material inserts the partial below the content on pages that opt in, and its built-in meta plugin lets a .meta.yml file in a folder set comments: true for everything beneath it, so a whole section can opt in with one file.

If your Material site uses navigation.instant, pages load without a full refresh, and a script inside the content area may not run again for the next page. Material exposes a document$ observable that fires on every page change. Add a JavaScript file through extra_javascript in mkdocs.yml containing:

document$.subscribe(() => {
  if (document.getElementById('echothread') && window.EchoThread) {
    window.EchoThread.bootstrap()
  }
})

window.EchoThread.bootstrap() is the method the widget exposes for single-page hosts; it re-mounts into whatever #echothread is on the page now.

Theming for documentation

Docs sites usually have a theme toggle, and the widget can follow it. data-theme="light" or data-theme="dark" pins a scheme; data-theme-source="--vp-c-bg" on VitePress, or --md-default-bg-color on Material, reads the current background from the theme's own CSS variable so the widget flips when the reader does. data-accent-color matches your brand, and data-font-family="inherit" uses the docs font. The full attribute list is in the docs.

What readers get, and what you keep

A reader with a correction can post it as a guest, or sign in with Google, GitHub, X or Facebook. You get threaded replies, a moderation queue where every comment can be held before it appears, and spam scoring on every submission. Comments are stored with EchoThread rather than in your repository, which is the trade against giscus: you lose "the discussion lives next to the code", and you gain readers who are not on GitHub. If most of your readers are on GitHub, the giscus alternative and utterances alternative posts lay out that trade in more detail rather than pretending it does not exist.

What it costs

EchoThread's Hobby plan is free for one site, with comments included, no ads and no reader tracking. Sites created from 1 October 2026 include 10,000 page views a month on Hobby; a site created before that date keeps unmetered page views. Paid plans start at $9 a month for three sites and 100,000 page views; see pricing for the full ladder.

For the wider question of whether documentation should have comments at all, and how to moderate them, see adding a comment section to technical documentation. If your docs are on Docusaurus rather than VitePress, the Docusaurus guide covers the equivalent theme swizzle.