The Disqus Comments Plugin

Disqus is a hosted commenting platform with threaded discussions, reactions, notifications, spam filtering, and moderation tools. The Disqus Comments plugin adds a Disqus comment section to selected posts and pages on your Publii site.

You need a Disqus account and a shortname registered for your website. The plugin supplies Disqus with the published page URL and the Publii post or page ID, helping each discussion remain connected to the correct piece of content.

Adding Comment Plugin Support to Older or Custom Themes

Current Publii themes include support for comment plugins. Follow this section only if you use an older theme or a custom theme that does not include the commentsCustomCode helper.

Open your file manager and go to Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME. Replace YOUR_SITE with your site's folder name and YOUR_THEME with the active theme's folder name.
Open the theme's post.hbs file in a code editor. If the theme has other post templates, update those files as well.

Near the end of the file, find the old comments block. It may 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}}

Replace it with:

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

Save the file.

Keep a backup of custom theme changes. A theme update can replace edited theme files.

Activating the Plugin

Open Tools & Plugins in Publii.
Find Disqus Comments and enable its switch.
Click the plugin card to open its options.
Enter your Disqus shortname, review the remaining settings, and save the changes.
Regenerate the website after changing the plugin configuration.

Creating a Disqus Site and Finding Its Shortname

A shortname is the permanent identifier Disqus assigns to a registered site. Disqus uses it to connect the embed with your community, comments, and moderation settings. Choose it carefully because Disqus does not let you rename it after registration.

Create an account at Disqus, or sign in to your existing account.
Choose the option to install Disqus on your site. If you already manage a Disqus organization, open its general settings and add a site there.
Register the site, choose its shortname, and complete the site settings. You can change the public website name later, but the shortname remains fixed.
Open the site's general settings and copy its shortname. You can also find it in an admin address such as mywebsite.disqus.com/admin, where mywebsite is the shortname.
Paste the shortname into the plugin's Disqus shortname field. You can enter mywebsite or the full mywebsite.disqus.com address.

Publii generates the Disqus embed, so you do not need to copy the Universal Embed Code into your theme.

Plan information: Disqus offers several plans. Its Basic plan is supported by advertising and has eligibility limits based on site traffic and the number of sites in an organization. Check the current Disqus plan details before choosing a plan.

Enabling Comments in Your Theme

The plugin supplies the comment box, while the theme decides where Publii can display it.

To enable comments for posts or pages across the site, open Theme and go to Custom Settings → Post Options or Page Options. Enable Display Comments.

You can also control comments for one post or page. Open the item in the editor, click the settings icon, choose Other Options, and change Display Comments.

Disqus Comments Plugin Options

Configure the Disqus connection, appearance, loading behavior, and cookie consent requirements in the plugin settings.

Required: Enter a valid Disqus shortname before publishing. Disqus cannot load the comment section without it.

Comments Configuration

Disqus shortname – The permanent identifier assigned to your site by Disqus. Enter the shortname alone, such as mywebsite, or paste the full mywebsite.disqus.com address.
Comments language – Overrides the language of the Disqus interface on pages generated by Publii. Enter a supported Disqus language code, such as en, pl, or de. Leave the field empty to use the language selected in the Disqus administration panel.

Appearance

Comments heading – Text shown above the comment section. Leave the field empty to hide the heading.
Heading level – The HTML heading level used for the title. H2 suits most themes, but you can choose H3 through H6 to match the page structure.

Messages

JavaScript disabled message – Text shown when a visitor has disabled JavaScript in the browser.

Advanced Styling

These fields are intended for theme developers. Keep their default values unless your theme requires different CSS classes.

Outer container CSS class – Sets the class on the outer element surrounding the comment section. The default value is comments.
Inner container CSS class – Sets the class on the inner comment container. The default value is comments-wrapper.
Heading CSS class – Adds a CSS class to the comments heading. Leave it empty to use the theme's standard heading style.

Loading

Load comments when visible – Delays the Disqus script until the visitor scrolls close to the comment section. This reduces work during the initial page load. Disable the option if you want Disqus to start loading with the page.

Cookie Banner Integration

Require cookie consent – Prevents the browser from downloading the Disqus script until the visitor accepts the selected Publii Cookie Group.
Cookie Group ID – The internal Group ID configured in Site Settings → Privacy Settings → Cookie Groups. Enter the same value in both places, for example comments.
Message before consent – Text shown where the comment section would appear until the visitor accepts the selected Cookie Group.

Configuring Cookie Consent

Use these steps if you enable Require cookie consent in the plugin:

Open Site Settings → Privacy Settings.
Enable the cookie banner and its advanced cookie configuration.
Add Disqus to a suitable group, such as a functionality or comments group.
Give that group a Group ID, for example comments. Use letters, numbers, hyphens, or underscores without spaces.
Return to the Disqus Comments plugin and enter the exact same value in Cookie Group ID.
Save the settings and regenerate the website.

Do not leave Cookie Group ID empty while Require cookie consent is enabled. The plugin will keep Disqus blocked because it cannot determine which consent should unlock the script.

Read Publii's cookie banner guide for details about external scripts and Cookie Groups.

Page Identification and Existing Discussions

The plugin sends the published page URL and a stable Publii post or page ID to Disqus. The ID connects the content with its discussion even if you later change the page slug or domain. You do not need to configure these values yourself.

Use one Disqus shortname consistently for the same site. Changing the shortname connects Publii to a different Disqus community, so existing discussions from the previous shortname will no longer appear.

Language Settings

Leave Comments language empty when every discussion should use the default language configured in Disqus Admin → Setup → Appearance. Enter a language code in Publii only when you want this plugin to override that setting.

For multilingual sites, Disqus recommends considering separate forums when each language needs separate moderation. See the Disqus multilingual website guide.

Preview Mode

The plugin does not load the live Disqus embed in Publii Preview. Disqus validates page addresses and trusted domains, while Publii Preview opens pages from a local file:/// address. The preview displays a status message in place of the embed.

Generate or synchronize the site and open the page from its published or test URL to check the comment form, selected language, and cookie consent flow.

Troubleshooting

No comment section appears – Confirm that the plugin is enabled, the shortname is present, and Display Comments is enabled for the current content type or item.
Disqus reports that it could not load – Check the shortname and test the published page. If you use Disqus Trusted Domains, add the website's domain in Disqus Admin → Settings → Advanced. Enter the domain without a protocol or path.
The consent message remains visible – Confirm that the Cookie Group ID in the plugin matches the Group ID in Privacy Settings, including capitalization.
Comments do not appear in Publii Preview – This is expected. Test the generated site from a public or staging URL.
A page shows the wrong or an empty discussion – Confirm that the site still uses the same Disqus shortname. If comments were previously embedded with a different page identifier, use Disqus migration tools to associate the old discussion with the current page.
The interface uses the wrong language – Clear the plugin's Comments language field to use the Disqus default, or enter a supported language code.

For current platform behavior, see the official Disqus guides to shortnames, JavaScript configuration variables, and embed troubleshooting.