The GraphComment Plugin

GraphComment is a hosted commenting platform that organizes replies into visual discussion threads. Readers can reply, vote, react, share discussions, and follow longer conversations through its Bubble Flow interface.

The GraphComment plugin connects the service to Publii posts and pages. You need a GraphComment account and the shortname assigned to your registered site. The plugin labels this value GraphComment ID.

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.

1. 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.
2. Open the theme's post.hbs file in a code editor. If the theme has other post templates, update those files as well.

3. 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}}

4. Save the file.

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

Activating the Plugin

1. Open Tools & Plugins in Publii.
2. Find GraphComment and enable its switch.
3. Click the plugin card to open its options.
4. Enter your GraphComment ID, review the remaining settings, and save the changes.
5. Regenerate the website after changing the plugin configuration.

Finding Your GraphComment ID

GraphComment calls this identifier a shortname or graphcommentId. It connects the embed with the correct website and community.

1. Create an account at GraphComment, or sign in to your existing account.
2. Add a website in the GraphComment back office.
3. Open that website and select its Setup tab.
4. Copy the shortname shown as the graphcommentId value.
5. Paste the value into the plugin's GraphComment ID field. Copy the identifier only, without quotation marks or the surrounding JavaScript.

Publii generates the current GraphComment embed, so you do not need to paste GraphComment's installation script into your theme.

Enabling Comments in Your Theme

The plugin supplies the discussion widget, 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.

GraphComment Plugin Options

The plugin settings control the GraphComment connection, initial discussion order, pagination, surrounding Publii markup, loading behavior, and Cookie Banner integration.

Required: Enter a valid GraphComment ID before publishing. GraphComment cannot load the discussion without it.

Comments Configuration

• GraphComment ID – The shortname shown in the GraphComment back office under the website's Setup tab.
• Default comment order – Sets the initial order for first-time visitors. Choose Newest first, Oldest first, or Most relevant. Select Use GraphComment setting to use the site-wide default from the GraphComment back office. A returning visitor's saved choice takes priority over the plugin setting.
• Discussions per page – Sets how many top-level discussion branches GraphComment loads on one page. Enter a number from 1 to 100. Leave the field empty to use the GraphComment setting. The option counts top-level discussions, not every reply inside them.

Appearance

• Comments heading – Text shown above the discussion. 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 change the Publii elements around the GraphComment widget. They do not style the interface inside the GraphComment iframe. Use the GraphComment back office to configure the widget's colors and appearance.

• 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 GraphComment script until the visitor scrolls close to the discussion. This reduces work during the initial page load. Disable the option if you want GraphComment to start loading with the page.

Cookie Banner Integration

• Require cookie consent – Prevents the browser from downloading the GraphComment 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 discussion 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:

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

Do not leave Cookie Group ID empty while Require cookie consent is enabled. The plugin will keep GraphComment 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. GraphComment also documents its GDPR and EU data residency measures. Your site owner or legal adviser should decide which consent settings the website requires.

Discussion Identity and URL Changes

GraphComment recommends assigning every discussion a stable uid. The plugin uses the Publii post or page ID for this value and also supplies the published page URL. You do not need to configure either value.

Keep the same Publii content ID and GraphComment ID to preserve the connection with an existing discussion. A custom embed that used another uid can create a separate discussion. Contact GraphComment or use its migration tools when you need to reconnect older threads.

Default Order and Returning Visitors

The plugin's Default comment order applies to first-time visitors who do not have another preference. GraphComment gives a visitor's own selection and saved account preference higher priority. A returning visitor can therefore see a different order from the one selected in Publii.

Preview Mode

The GraphComment platform can work on localhost, but this Publii plugin does not load the live external widget in Publii Preview. It displays a status message in its place. This keeps preview behavior consistent with Publii's other external comment integrations.

Generate or synchronize the site and open the page from a published or staging URL to check the discussion, selected order, pagination, and Cookie Banner flow.

Troubleshooting

• No discussion appears – Confirm that the plugin is enabled, the GraphComment ID is present, and Display Comments is enabled for the current content type or item.
• The GraphComment ID is rejected – Copy the shortname from the website's Setup tab without quotation marks, spaces, or surrounding embed code.
• The selected order is not used – GraphComment remembers visitor and account preferences. Test in a new browser profile or clear the saved preference before checking the initial order.
• Discussions per page has no effect – Enter a whole number from 1 to 100. An empty or invalid value makes the plugin use the GraphComment default.
• 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 a new empty discussion – Check whether a previous custom integration used another uid or GraphComment ID. Discussion identity must remain unchanged.
• CSS classes do not change the widget colors – The plugin's CSS fields style the Publii containers and heading. Configure the embedded interface in the GraphComment back office.

For current platform behavior, see the official GraphComment guides to getting started and widget configuration.