Update: This tutorial is outdated. There is an updated tutorial available.

In my earlier post I referred to jskomment, the open source comment system that I use, and I thought that I would create a quick tutorial on setting it up and integrating it with Pelican.

However, This tutorial is easily adaptable for use with any website.

Background

jskomment is an open source AJAX-powered commenting system. It is developed by Martin Monperrus and licensed under the MIT License.

It is relatively light weight and comes with two server-side implementations. One is a Java version for use with the Google AppEngine and the other is PHP-powered. This tutorial deals solely with the PHP version.

Additonally, jskomment is completely themable via CSS and offers the unique ability to support multiple discussion threads per page should someone wish to do so.

Getting started

In order to acquire jskomment you will need to clone a local copy of its repository with Mercurial by issuing the following command:

hg clone https://code.google.com/p/jskomment/

Now that you have a copy of jskomment on your system we are going to need the PHP files from jskomment/src/php/ and the most of the files from jskomment/war/ as we do not need the WEB-INF folder or the HTML files.

I would also recommend that you take a moment to update the supplied json2.js file with a much more recent version available from https://github.com/douglascrockford/JSON-js

Important File Change

jskomment does have one flaw which you need to fix before you go live with it. I discovered that it does not seem to properly sanitize the output so it will display any HTML that it is given. I created a very simple fix which will remove the ability to display HTML in comments.

Open jskomment.php and find the following line:

foreach(file($fname) as $comment) {

Add the following piece of code directly under it and then save the file:

$comment = htmlspecialchars(strip_tags($comment), ENT_NOQUOTES, 'utf-8');

I have emailed the developer about this issue and he will hopefully see it and apply a proper fix with his next release.

Website setup

Create the folder jskomment in your website's root directory. You can do this through your FTP client or through SSH via issuing the following command in the proper web directory:

mkdir jskomment

You then need to upload all of jskomment's files to the directory.

Next you will want to create the folder jskomment-data within the jskomment folder. This folder is where jskomment will store all of your comments.

mkdir jskomment/jskomment-data

In order for jskomment to work properly via PHP it needs a few entries added to your .htaccess file which allow it to essentially pretend to be a JavaScript file. This is done by simply appending the following lines into your existing file or creating a new file if required:

RewriteEngine on
# serving the composite js file
RewriteRule ^jskomment/jskomment.js$ jskomment/jskomment.php?file=jskomment.js [QSA,L]

# test service
RewriteRule ^jskomment/t$ jskomment/jskomment.php?action=t [QSA,L]

# getting a list of comments
RewriteRule ^jskomment/s$ jskomment/jskomment.php?action=s [QSA,L]

# getting a list of list of comments
RewriteRule ^jskomment/sx$ jskomment/jskomment.php?action=sx [QSA,L]

# posting a new comment
RewriteRule ^jskomment/p$ jskomment/jskomment.php?action=p [QSA,L]

Once you have completed this the last step for you to do is to add jskomment to your HTML code where you want it to show up on the page.

Edit your Pelican theme's article.html file and add the following directly above {% if DISQUS_SITENAME %}:

<div class="comments">
  <h2>Comments?</h2>
  <div class="jskomment" title="{{ SITEURL }}/{{ article.url }}"></div>
  <script src="{{ SITEURL }}/jskomment.js"></script>
  <script>JSKOMMENT.url="{{ SITEURL }}/jskomment";</script>
</div>

Save it and recreate your static HTML files via make html as usual.
Once you have reuploaded your files you should have a working installation of jskomment.

All that is left is for you to change how it looks so it suits the design of your website better.
You can do this by editing the CSS in jskomment.css to your liking.

Anti-Spam Support (Optional)

jskomment has built-in support for reCAPTCHA to help combat comment spam. If you do not have an account you will need to get one as it requires a supplied public and private key to work.

Open jskomment-core.js. You will need to edit the lines that contain JSKOMMENT.url = and JSKOMMENT.recaptchaPublicKey = and adapt them to your website.

It should look like the following when you are done.

JSKOMMENT.url = 'http://yourwebsite.com/jskomment';
JSKOMMENT.recaptchaPublicKey = "Your_reCAPTCHA_Public_Key";

Finally, you will need to create a file called jskomment.local.php and insert the following code:

<?
    @define('RECAPTCHA_PRIVATE_KEY','Your_reCAPTCHA_PRIVATE_Key');
?>

Save and upload the two files and you will be done.