Home

Welcome to the Jekyll-Disqus wiki!

Jekyll-Disqus is a small plugin for Jekyll that provides the tags to embed the Disqus code and display a comment counter or the user interface used to insert the comments.

In practice, each of them consists of an HTML code that must be placed in the same place we want to see these elements rendered, and a Javascript code that should go, together with other Javascript codes, at the bottom of the page before the body tag is closed.

To associate a comment thread with every post, an identifier must be associated, this identifier must also be unique, otherwise, the same comments might appear on two different pages.

What this script does is generate a unique ID starting from the publishing date, automatically. When it is not provided (i.e. on pages or collections), a disqus_id can be manually assigned in the front matter.

In addition, it also ensures that every ID is really unique and that every post or page that should provide an ID to that script, it really does that!

That is the main difference between this plugin and a Liquid script that might be included in the theme to achieve the same result: a Liquid script isn't powerful enough to ensure the ID integrity.

Installation

There are two equivalent methods using Bundler.

Two steps

Just like other Jekyll plugins, it can be installed by including the gem name in the :jekyll_plugins group inside the Gemfile file:

group :jekyll_plugins do
  ...
  gem 'jekyll-disqus-plugin'
end

Then with bundler from the terminal download it and bundle to the project:

$ bundle install

One step

Otherwise in one step just type:

$ bundle add jekyll-disqus-plugin --group "jekyll_plugins"

Configuration

The configurations in the _config.yml file are very minimal and go under the jekyll-disqus key:

jekyll-disqus:
  shortname:
  id_prefix: 
  post_selector: 'include.post'
  ui:
    layouts:
    - 'post'
  counter:
    layouts:
    - 'all'

shortname : It is a mandatory setting and requires the same Shortname provided by Disqus for each website added.

id_prefix : It is a code that will be prepended to the Disqus Ids, manual or automatic, just to add another level of customization, for example, I used FA- for my Freeaptitude blog.

post_selector : This is how the script will read the post data from within a paginator layout and will be able to extract the info to create the ID used by the counter tag. By default, it is include.post, as it is supposed to recall the preview template generator using the post variable but in case the content is assigned with a different variable it can be changed here.

ui.layouts/counter.layouts : This is a list of layouts where the two couple of tags are allowed.

Enable and disable

Usually the Disqus comment box is shown in full rendered posts that use the post layout, while the Disqus counter might appear both in the mentioned pages but also in a paginated page layout, that's why the all keyword is the better choice.

To include the comment box script on a content that makes use of a different layout, let's say download, it must be included in the list:

ui:
  layouts:
  - 'posts'
  - 'download'

To completely exclude specific pages, posts or pages, we can place the no_disqus field set to true on its front matter.

---
title: ...
...
no_disqus: true
---

Custom Disqus ID

As told before this plugin will try to generate automatically the ID used to connect the post with a particular thread using the publishing date, but in those situations where the date is not available, the ID can be explicitly declared in the front matter of our content within the disqus_id field:

---
title: ...
description: ...
author: ...
...
disqus_id: 'CUSTOM_DISQUS_ID'
...

Be sure that:

• The custom disqus_id will remain unique or an error will be thrown at the building time;
• the custom disqus_id won't change once the page has been published, or all the comments associated with the post will be lost;
• the publishing date, where the ID is not customized, won't change, or all the comments associated with the post will be lost.

Tags

The tags provided are quite self-explanatory.

Those having the script keyword in their name (disqus_script_counter and disqus_script_ui) must be included once before the HTML body tag ends, just like any other Javascript code, at the bottom of those page layouts including also one of the other tags inside the page itself.

<HTML>
  <HEAD>
  ...
  </HEAD>

  <BODY>
  ...
  {% disqus_script_ui %}
  {% disqus_script_counter %}
  </BODY>
</HTML>

The disqus_ui tag renders the Disqus comment area, and usually takes place at the end of the post, just after the content and before other blocks, but that's mostly a matter of personal taste. To render correctly the comment area, the aforementioned disqus_script_ui must be placed at the bottom of the post template.

The disqus_counter tag displays the number of comments that a certain page collected on its thread. This tag can be used near the other info, after the title, in both a fully rendered post page or just in the headline of a paginating layout. This tag also accepts a label parameter which will appear beside the counter:

{% disqus_counter label="Comments" %}

The page containing the counter(s) must also include the disqus_script_counter at the bottom of the page.

In the table below a summary.

Tag	Description	Template
{% disqus_counter %}	The count of comments under a certain post	Post
{% disqus_script_counter %}	The required Javascript that renders the counter	Default
{% disqus_ui %}	The comment box	Post
{% disqus_script_ui %}	The required Javascript that renders the comment box	Default

Resources

• Project page on FreeAptitude.