The Disqus Comments Plugin

Disqus is one of the most popular comment systems on the internet today, used across thousands of sites around the world. Users can sign-up to Disqus, and then post comments to any site using Disqus comments through this one account; no need to create individual user accounts for each site. It also includes additional features that may not usually be included with site-specific comment systems, such as notifications of replies or other activity, and moderation tools for managing users and posts.

As the name suggests, the Disqus Comments Plugin integrates Disqus into your Publii site, allowing you to allow comments from users on any post that you specify.

Adding Comment Plugin Support to Your Theme (for older or custom themes)

If you are using a earlier version of the Publii themes, or your own custom theme, then before you can use the comments plugins available from the our Marketplace you will need to make a small change to your theme's post.hbs (also in other post-templates) file to enable the comments to function correctly. To do so, follow these steps:

Open your preferred file explorer app, and navigate to the Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME folder.
where 'YOUR_SITE' is your site's name, and 'YOUR_THEME' is the folder for the theme that you are currently using on the site.
Using the code editor of your choice, open the post.hbs file (this can be opened in basic apps such as notepad, if you don't have any special code editor installed).

Near the bottom of the code list, find the section which might look like this:

{{#if @config.post.displayComments}} 
    <div class="post__comments"> 
       <div class="wrapper"> 
          <h2 class="h5">{{ translate 'post.comments' }}</h2> 
       {{> disqus}} 
       </div> 
    </div> 
{{/if}}

And change it to:

{{#if @config.post.displayComments}}
    <div class="post__comments"> 
       <div class="wrapper"> 
          {{{@commentsCustomCode}}}
       </div> 
    </div> 
{{/if}}

Once you have edited the file, save the changes; you will now be able to use the comments plugins without issues.

Activating the Plugin

The plugin can be enabled by clicking the switcher button in the Disqus Comments box of the Tools & Plugins section of the Publii app. If the switcher changes from grey to blue then the plugin is enabled. However, there are some options that are required to be completed before the plugin can be fully activated. To open the options menu, click on the Disqus Comments box again, anywhere except on the switcher button. This will take you to the Disqus Comments option page.

Enabling Comments

Activating the Disqus Comments plugin on its own will not allow Disqus to display comments on your site; you will need to change the Comments option in your theme settings first. Once enabled, Publii will create a comments area on the page where the plugin can display. To use comments on your site, first navigate to the Theme section of the app by clicking the option in the left-sidebar menu, then navigating down to the Custom Settings → Post Options section of the Theme Settings and enable the Display Comments option.

Alternatively, you may enable comments on individual posts on a case-by-case basis when creating a new post or editing an existing post by clicking on the Settings icon in the top-right of the editing area (represented by a cog) to open the settings, then clicking on the Other Options option to see the full selection of options. At the bottom of this section will be the Display Comments option, which you can enable/disable specifically for that one post.

Creating a Disqus Shortname

In order to use the Disqus Comments Plugin, you will first need to ensure that you have registered your site on Disqus, and received a shortname for your site. The shortname is an identifier that Disqus uses for your site, so that it can ensure the correct comments and conversations are loaded and displayed via the plugin.

Registering your site and creating a shortname is a very quick and easy process; simply follow these steps:

Go to the Disqus Website and click on the Get Started button in the top-menu or on the frontpage to begin creating an account, or the Log-in button if you already have an account (if you already have an account, skip to step 3).
Enter the details you wish to use to create the account; you'll only need to enter a name, email and password. Alternatively, you can log-in automatically via your Google, Twitter or Facebook accounts by clicking the relevant icon above the fields.
Once you've logged in/created an account, you'll be taken to a screen where you can choose between two options; "I want to comment on sites" and "I want to install Disqus on my site". Click the second option.
You'll now be on the "Create a new site" page. The Site Owner field will already be completed via your account details, but you will need to enter your site name in the Website Name field. Once you have entered the name, hit the Tab key or click away from the field; your automatically-assigned shortname will be displayed underneath the Website Name field. If necessary, you can choose to customize this name by clicking the Customize your URL text under the field; this will open a new option where you can enter an alternative shortname. Note that your shortname must be unique; you will see a message if your chosen shortname is unavailable.
Select a category for your site from the drop-down list next to the Category field; this does not affect the function of the comments section; it is only for informational purposes. At this point, copy the shortname from underneath the Website Name field; you'll need to enter this in the plugin options in Publii. The shortname should look like, for example, test-7cXugZEU7x.disqus.com.
Next, you'll be able to select a plan. There are paid options that include additional features, but if you simply want to include comments without any additional payment, you may use the "Basic" plan (note that using this plan will include advertisements in the comments section of your site). For the Basic plan, just click the Subscribe Now button.
The next section deals with installing Disqus on your site; this section can be safely ignored as Publii will take care of all the necessary steps once you have entered your shortname into the plugin options. Instead, click the "I don't see my platform listed..." option, then on the next page (which includes instructions on installing manually), scroll to the bottom of the page and click the Configure button to move on to the next step.
The next few sections are straightforward, allowing you to enter additional details such as the website URL, a link to your comment policy page, set the comment section language, and other basic options, as well as the standard settings for allowable content within the comment sections. Fill these out as necessary. Once done, your Disqus setup is complete. Simply add your shortname to the Disqus Comments plugin options in the Publii app, and you'll be ready to go!

Disqus Comments Options

The options available in this plugin are fairly straightforward, and we will cover them and their function in this section.

Note: The Disqus shortname option must be configured before the Disqus comments section can be added to your site.

The available options are:

Comments configuration

Disqus shortname - The Disqus shortname refers to the unique identifying shortname URL provided when registering your site with Disqus. Details for doing this may be found in the preceding section.
Language - Sets the language that will be used for the Disqus-generated text in the comment section.

Theme Integration

Header Title - Text entered in this field will be used as the title for the comments box on your site.
Heading Level - Sets the header size/styling that should be used for the header title.
Fallback Message - Text entered in this field will be displayed if the comments box is unable to load due to the user disabling scripts or using a browser that doesn't include support for scripts. By default it advises that JavaScript must be enabled to display comments.
Comments Wrapper - Sets a custom CSS class for the comments wrapper; that is, the outer area surrounding the comments section. Leave this as the default to use the standard styling set in the theme code.
Comments Inner Wrapper - Sets a custom CSS class for the inner wrapper of the comments; the inner area of the comments section. Leave as default to use the theme's built-in comment styling.
Comments Heading - Sets a custom CSS class for the heading text of the comments section, for additional styling options on top of or alternatively to the default styling that is applied to the respective H2-H6 text. Leave as default to use the standard theme styling.
For example, for semantic purposes, you want to leave heading H2 but reduce its font size, so you can use one of the available classes in our themes: h1 h2 h3 h4 h5 h6
To change the text alignment, use the following classes: align-left align-right align-center

Advanced Options

Lazy Load - Enabling this option allows the comments section to utilise Lazy Loading. This uses moments when the browser is idle to start pre-loading the comments section as the user scrolls down the page to reduce the delay before comments are displayed.

Cookie Banner Integration

Enabling this adds an option allowing users to consent to the cookies used by Disqus into the built-in Publii cookie banner. Once this option is enabled, two more options will become available:

Cookie Group ID - Enter a name here for the cookie group that the Disqus cookies should be included in; e.g. ’comments’. Make sure to add (if it doesn't exist) this group name to the GDPR section of the site settings. You can find instructions on how to do this in the GDPR section of this documentation.
Fallback Message - Sets a message that should be displayed if the user does not consent to using Disqus scripts. By default, this will advise users that they need to change their cookie preferences in the banner before comments can be displayed.