Disqus 101 How to optimize Disqus for your community
Guide

How to optimize Disqus for your community

We want to help all of our publishers fit Disqus into their communities as successfully and efficiently as possible. This starts with account setup and ends with our optimization and troubleshooting options.
How to optimize Disqus

Using Disqus web integration

Before installing Disqus, you'll need to register a forum. This integration guide isn’t specific to any platform and assumes you know how your website’s system works. We also recommend some basic understanding of JavaScript/HTML.

For many of the most popular platforms (e.g., WordPress), most of these steps are unnecessary as we have integrations that do all of this for you. See our list of available integrations to find out if yours is listed.

Comments embed

The comments embed is the core Disqus experience where most users will spend their time. By putting a snippet of code on your website, we’ll load all the necessary components for commenting experience on a specific post, article, or topic.

  • Universal code is the basic drag-and-drop embed code to show the commenting embed.
  • Configuration variables let you add a unique identifier, specify a link-to URL, and a title (among others) to be stored with your thread. These aren't required but are highly recommended.
  • Multilingual websites allow you to override the language the embed UI displays from what you've set globally in your site settings. Using the this.language JavaScript variable can dynamically load the Disqus embed in different languages per page. For a complete list of language codes, see Languages on Transifex. Disqus does not support all languages offered in Transifex. For a complete list of supported languages, see the Disqus project on Transifex.
  • Callbacks allow you to attach JavaScript to specific events in the Disqus embed. Most commonly, this is used for tracking in your analytics system but can be used for almost anything that doesn't impact the user experience negatively.
  • AJAX sites detail how to reload the Disqus thread for AJAX/single-page applications without navigating to a new page.
  • Secure (HTTPS) sites are handled out of the box with the current embedded code. See this guide if you still need to update the embed code or need help with mixed content errors.
  • Single Sign-On (SSO) provides a seamless log-in experience to your users by allowing them to sign in to your site and fully use Disqus without again authenticating with Disqus.

Comment counts

You can display a comment count link anywhere on your site. This involves adding a small script and appending #disqus_thread to the end of href links. You can customize comment count link text at your Disqus admin's Settings > Community page. You can also translate the comment count above the postbox.

To add the comment count, follow these steps:

  1. Paste the following code at the bottom of your index or home page before the closing </body>. <script id="dsq-count-scr" src="//EXAMPLE.disqus.com/count.js" async></script>.
  2. Change the short name variable from EXAMPLE to whatever the short name is of the forum you're using. Your short name can also be found on your forum's Admin > Settings > General page.
  3. On the index or home page, append #disqus_thread to the end of each article URL which appears inside the href tag for the article comments link. This will tell Disqus which links to look up to return the correct comment count. Example: <a href="http://example.com/article2.html#disqus_thread">Second article</a>. See Counts for non-link elements below if you're not using <a> tags.

By default, Disqus looks up the count using the comment count link's href attribute. However, you can also look up the count using a Disqus identifier. To do this, add a special attribute data-disqus-identifier to your links.

Note: This requires setting a Disqus identifier on the comment threads themselves. Typically this is done using the this.page.identifier variable. See our JavaScript configuration variables for implementation steps.

If you cannot use Disqus identifiers with your Disqus install, that's okay. Disqus will look up threads by their associated URLs using the href attribute in comment count links on your site by simply not adding this attribute. However, we highly recommend using the Disqus identifier since URLs can change.

For the following link, Disqus will fetch the comment count by the identifier: article_1_identifier

Example: <a href="http://example.com/article1.html#disqus_thread" data-disqus-identifier="article_1_identifier">First article</a>

Counts for non-link elements

To add comment counts to <span> and <div> elements, add the class disqus-comment-count and the attribute data-disqus-identifier or data-disqus-url. Example:

<span class="disqus-comment-count" data-disqus-identifier="article_1_identifier">First article</span>

<span class="disqus-comment-count" data-disqus-url="http://example.com/article1.html">First article</span>

Updating counts

By default, Disqus will reload the most recent comment count with every new page load that includes count.js. Once count.js is loaded, you call the following function if you'd like to poll and update the comment count dynamically:

DISQUSWIDGETS.getCount({reset: true});

One everyday use case of this function is to update page elements unavailable via the initial load of count.js.

Customizing comment count link text

You can customize comment count link text at your Disqus Admin > Settings > Community page.

Example scenario: Some websites show comment counts in a small circle or square and thus remove everything but the integer from their comment count links.

Note: The comment count text customization above only applies to links on your homepage or any other page that you load count.js—it is impossible to edit the comment count that displays above the comment embed.

Best practices

  • If you're using Disqus outside of a publicly accessible environment, see our guide on Best practices for staging, development, and preview sites at this link or below.
  • If using configuration variables with the embed, set them before loading the page. None of the data you give these variables will apply after the thread is created, so they must be present before the page is loaded for the first time.
  • Setting a trusted domain in your Disqus admin settings will ensure no other websites can use your Disqus short name. Ensure you include all possible domains you might load the Disqus embed on, or else you'll block yourself.
  • We recommend Resetting and Archiving Large Threads when a discussion on your site grows larger than 5,000 comments. Large threads present some user experience issues and can be avoided by configuring your automatic close setting. See more on this below.

Using the Disqus API

The Disqus API provides a way to see many different points of data relating to comments on any site. It is designed as a supplemental data source and will provide a challenging method for replacing the comments embed. Once you've created a Disqus account, you can create an API application by following the guide here.

By default, the API will have a rate limit of 1000 calls per hour. Unlimited API access is currently available as an add-on for users with a Pro-level subscription. If you want to subscribe to Pro, you can do so in your subscription settings at Admin > Settings > Subscription and Billing.

Here's a list of relevant guides for how to utilize our API:

Best practices for staging, development, and preview sites

The content you store on Disqus should be properly sandboxed if your site uses a staging, testing, development, or preview site emulating live content. These are some tips on ensuring that invalid data doesn't leak onto your live site.

Use a neutral Disqus account when registering forums

This is a standard Disqus account controlled by your company or organization, which can be easily transferred as different members take on administrative duties within your Disqus forum.

Also, certain account aspects, such as API applications, can't be transferred and must be recreated.

Register multiple short names

Each short name is sandboxed from the other, and you can use that to keep test data away from the live site. For example, if you had the short name gotham installed on http://example.com/ and have a staging site at http://staging.example.com/, register and use the short name staging-Gotham for that server.
Note: There is no limit to the number of short names an account can register.

Personalizing your site

We offer several ways publishers can customize Disqus to reflect the voice of their site and community:

  • Upload a default commenter avatar: Add a default site avatar for commenters who don’t have one yet. This is an excellent way to make readers feel like a part of the community.
  • Create a custom moderator badge: Moderators on your site have a special badge next to their comments verifying who they are. By default, this reads "Mod," but you can easily customize this.
  • Set the default sort order: If a commenter hasn't chosen a preferred sort order, the default you set is used instead. The default option of "Best" is recommended for most sites.
  • Update the color scheme and typeface: Disqus automatically checks your site's font and background color and adapts to either a light or dark color scheme, along with a serif or sans-serif font. If these are detected incorrectly, you can override them.
  • Customize link color: Disqus inherits your site's link colors and will use this color for all links, the Load More Comments button, and the upvote/downvote buttons when clicked. For this to work, you'll need to ensure the relevant CSS rules are inheritable by Disqus. If Disqus isn't inheriting your site's link color, this may require changing link colors in your publishing platform's (e.g., Tumblr or Squarespace) settings or editing your site's CSS stylesheets directly. To figure out which link color Disqus is inheriting:
    • Locate <div id="disqus_thread"> 
    • Insert an <a> tag into disqus_thread. This requires editing HTML in the web inspector.
    • Inspect the anchor tag > expand the Computed Style dropdown > observe the 'color' parameter. This is the color that is being inherited.

The following customizations require a Pro or above subscription to enable:

  • Disable Disqus branding: If you have a Pro subscription plan, you can remove the Disqus logo from your footer. You can update this by going to the General Settings page in your Disqus Admin. Unchecking the Disqus Branding option will remove the Disqus logo from the right side of the footer.
  • Disable social share icons: This will allow you to disable the Facebook and Twitter social sharing buttons at both the comment and thread level. When on the Pro plan, you may disable social sharing here. Please note that even with social sharing icons disabled, a share option will still appear at the comment level but will only contain a direct link to the comment, with the previous Facebook and Twitter comment share options removed.
  • Use custom fonts: For sites with a Business subscription, various fonts will be available. The desired font may be selected from the Typeface section of the General Settings page. Business Publishers may also request that new fonts be added to the Disqus system. To be assessed for addition, the font must meet the following requirements:
  • Customize discussion prompts: This will allow you to customize the text in your postbox. This text will read "Start the discussion" for a thread with zero comments and "Join the discussion" for an active thread. With this feature, you can use any text with a 45-character limit. This change will apply to all threads on your site.
  • Customize default thread length: This feature allows you to customize how many comments are shown in the embed when Disqus first loads on the page. This can be used to have Disqus load a smaller window when it first appears on the page. By default, 50 comments will load initially on the desktop, and 20 comments will load initially on mobile. This feature can be used to show any number of comments below 50 on the initial embed load. Please note that even with this customization enabled, clicking "Load More Comments" will load 50 comments on desktop and 20 comments on mobile.
  • Customize width, margin, and padding: Disqus is set to fill 100% of the width of its parent HTML element and has no margin or padding set on its <div>. Disqus often looks best when its parent container gives it some margin or padding. Additionally, the width of the disqus_thread ID can be adjusted using CSS.

Importing and exporting comments

Disqus supports several XML formats natively for comments. You must adapt your comments to our Custom XML import schema if they are not in these formats.

  • Make sure the files you're importing are valid XML. You can use the W3C xml validating tool to check.
  • Compressed files (e.g., .zip, .gzip) can't be read by default, so make sure you've decompressed these before uploading them.
  • Unless you've changed some comment data, the importer will filter out duplicate comments.
  • Email addresses are unique identifiers in Disqus, so ensure each user has their email address before importing. Otherwise, all comments will appear from the same user.
  • Imported comments can't be permanently deleted. Consider following our guidelines for development sites to make sure the data you're importing is correct.

Importing comments into Disqus

Watch this video to understand how to import comments into Disqus across platforms.

https://youtu.be/qQ8i6cYhGzk

Exporting from Disqus

Disqus provides export of all comments on your site in a g-zipped file. This is in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready.

Note that this file can't be re-imported into Disqus as-is.

Please note: Exports may only be available for some sites. If you've requested an export file more than twice and still have not received a download link from us, an export for your site is likely unavailable.

Export format (XML)

Other methods

These are other ways you can import/export/sync comments that we do not support.