Add Disqus Comments to Docusaurus Blog Posts in 2025

TL;DR In my previous, now archived, article Add Disqus Comments to Docusaurus Blog Posts (archived) in 2021, I have discussed how to add the Disqus blog comments to a Docusaurus blog. At the time, Docusaurus was in the beta of v2.0.0, React was in v17, and I have used the JavaScript version of swizzling. But the trick I used gained some attention and there were several very inspiring comments, which you can see there. Unfortunately, due to my personal situation I have not acted on them. Until now!

UPDATED May 23, 2025

In this article you can read how Disqus comments can be added today, in 2025 using the latest and the greatest Docusaurus 3.8.0, React 18 or 19, and TypeScript instead of JavaScript. Of course, if your project needs JavaScript, you can just omit the types.

Let's Go

Prerequisites

Here's what you'll need to get started:

1. your project must be running Docusaurus v3 with at least one blog post;
2. you have installed your project using theme-classic
3. a terminal session open in the root of your project;
4. an account with Disqus with your registered Docusaurus web-app.

Install disqus-react and @docusaurus/plugin-content-blog:

pnpm add disqus-react @docusaurus/plugin-content-blog
# or
npm add disqus-react @docusaurus/plugin-content-blog
# or
yarn add disqus-react @docusaurus/plugin-content-blog

If you need some guidance on Disqus weblog registration, see my Register Your Weblog with Disqus section below.

---

Prepare the Frontmatter

Run your Docusaurus project locally running either yarn start or npm run start in your terminal. Browse to http://localhost:3000/blog and make sure you see at least one blog post. Choose one of them to work with.

Open the chosen blog post file in your editor of choice and add the following lines in the frontmatter:

---
slug: your-blog-post-slug
...
draft: true
comments: true # for Disqus
isBlogPostPage: true
---

1. The slug should be unique between different blogposts.
2. Keep draft value as true until you know for sure everything works fine. What it does is that it lets you see your post while running Docusaurus on localhost but not on the published website. When you are ready, set it to false or remove completely from the frontmatter.
3. The comments property lets you decide for each blog post if you want your visitors to be able to leave comments. In most cases, you can omit it or set it to true--the comments section will be present by default. Set it to false if you don't want any Disqus comments underneath your blog post.
4. isBlogPostPage is a hack. It is necessary for each blogpost with comments set to true. It seems like a duplication for the comments property but it plays a different role. Without it, the comments are visible and can be placed underneath the short form of the article on the /blog url.

Swizzle the BlogPostItem component

Swizzling a Docusaurus component means either adding a wrapper for or including the source code of a core component into your project. This allows us to customize the component's functionality. The application will then use the swizzled and customized version of the component instead of the standard one. In our case, we will be using swizzling to add the Disqus comments on our blog post pages.

Following the tip about adding comments on the Swizzling page, let us wrap the BlogPostItem component. Run the following command and accept the warning about the risks:

pnpm run swizzle @docusaurus/theme-classic BlogPostItem --danger
# or
npm run swizzle @docusaurus/theme-classic BlogPostItem --danger
# or
yarn swizzle @docusaurus/theme-classic BlogPostItem --danger

Choose TypeScript and then Wrap.

DiscussionEmbed

Open the index.tsx file inside src/theme/BlogPostItem and let us add our custom code. I have followed the instruction from the disqus-react repository. Also, applied the hint of pjnovas (a huge round of applause! 👍), which you can find in the discussion hereunder.

Replace the contents of the swizzled src/theme/BlogPostItem/index.tsx with the following code:

src/theme/BlogPostItem/index.tsx

import { useBlogPost } from '@docusaurus/plugin-content-blog/client'
import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
import BlogPostItem from '@theme-original/BlogPostItem'
import type { Props } from '@theme/BlogPostPage'
import { DiscussionEmbed } from 'disqus-react'
import React from 'react'

export default function BlogPostItemWrapper(props: Props): React.ReactElement {
  const {
    metadata: { frontMatter },
    isBlogPostPage,
  } = useBlogPost()
  const { comments = true, slug, title } = frontMatter
  const identifier = slug.split('-').join('_')
  const { siteConfig } = useDocusaurusContext()
  const baseUrl = siteConfig.url + siteConfig.baseUrl
  const url = `${baseUrl}blog${slug}`

  return (
    <>
      <BlogPostItem {...props} />
      {isBlogPostPage && comments && (
        <DiscussionEmbed
          shortname='your-short-name'
          config={{
            identifier,
            language: 'en_US',
            title,
            url,
          }}
        />
      )}
    </>
  )
}

And replace the contents of the index.d.ts file:

src/theme/BlogPostItem/index.d.ts

/// <reference types="@docusaurus/plugin-content-blog" />
/// <reference types="react" />
import type { Props } from '@theme/BlogPostPage'

export default function BlogPostItemWrapper(props: Props): React.ReactElement

If your web application has been properly registered with Disqus, you should see the Disqus comments appear under every blog post. Once you got it working locally you may set draft: false in the frontmatter or remove the setting completely and publish your project. The comments block will be there as well.

caution

The comments you add when testing your website locally do not synchronize with the comments of the same deployed page.

DO NOT CHANGE YOUR SLUGS

Be careful with changing slugs. Your existing comments are connected to it. If you change the slug, you will loose them. If that happens, just restore the old slug.

CommentCount and CommentEmbed

Using the disqus-react code snippets for CommentCount and CommentEmbed it is also possible to add those to your Docusaurus project in a similar manner.

---

Final Observations

While swizzling is handy, it is still some sort of a patch or workaround. So, if Docusaurus in some future release changes the code or signature of the component, you will probably need to swizzle the new version of the component as well as reapply the patch described here. This has already happened to me once with the BlogPostPage component.

Also, the Docusaurus CLI also evolves. In 2.0.0-beta.16, I was ejecting the complete BlogPostPage component and changing the core code inside. Then in January 2022, there came the --wrap option. Today, in 2025 it did not work for me either, so I used the --dangerous one 😄.

Ultimately, adding a comments section via Disqus is more than just a technical implementation; it's about building a vibrant community around your Docusaurus blog. Docusaurus, a robust and well-designed documentation framework, makes this customization possible, providing a clear path to achieve that in 2025 and ensuring your readers have a platform to engage, ask questions, and contribute, even as the framework evolves. Empower your readers to connect with your content today.

---