Tips & Tricks

Sections covered in this document:

Lazy-loading on scroll

You can defer loading the embed.min.js script until the user has scrolled to the bottom of the page:

<script type="text/javascript">
    // Lazy-load isso only when page end is in view
    function loadIsso() {
        var script = document.createElement("script");
        script.setAttribute("type", "text/javascript");
        script.setAttribute("src", "/prefix/js/embed.min.js");
        // add relevant data-isso attributes here
        script.setAttribute("data-isso", "/prefix/");
    let offset = 50; // Start loading 50px before reaching bottom
    function scrollBottomListener(ev) {
        if ((window.scrollY + window.innerHeight)
                >= (document.documentElement.scrollHeight - offset)) {
            window.removeEventListener('scroll', scrollBottomListener);
    window.onload = function() {
      // If viewport >= page height, load immediately
      if ((window.scrollY + window.innerHeight)
                >= (document.documentElement.scrollHeight - offset)) {
      } else {
          window.addEventListener('scroll', scrollBottomListener);

Note that loading additional content only after user interaction is bad for SEO. Additionally, users could experience a “jank” effect.

Use lazy-loading only if you are desperately trying to save bandwidth. By specifying async in the <script tag, loading the Isso Javascript will not render-block anyway.

Advanced Migration

In quickstart we saw you can import comments from Disqus or WordPress. But there are a many other comments system and you could be using one of them.

Isso provides a way to import such comments, however it’s up to you to to:

  • dump comments

  • fit the data to the following JSON format:

    A list of threads, each item being a dict with the following data:
    - id: a text representing the unique thread id (note: by default isso
          associates this ID to the article URL, but it can be changed on
          client side with "data-isso-id" - see :doc:`client configuration <../configuration/client>` )
    - title: the title of the thread
    - comments: the list of comments
        Each item in that list of comments is a dict with the following data:
        - id: an integer with the unique id of the comment inside the thread
          (it can be repeated among different threads); this will be used to
          order the comment inside the thread
        - author: the author's name
        - email: the author's email
        - website: the author's website
        - remote_addr: the author's IP
        - created: a timestamp, in the format "%Y-%m-%d %H:%M:%S"


        "id": "/blog/article1",
        "title": "First article!",
        "comments": [
                "author": "James",
                "created": "2018-11-28 17:24:23",
                "email": "",
                "id": "1",
                "remote_addr": "",
                "text": "Great article!",
                "website": "http://fefzfzef.frzr"
                "author": "Harold",
                "created": "2018-11-28 17:58:03",
                "email": "",
                "id": "2",
                "remote_addr": "",
                "text": "I hated it...",
                "website": ""

Keep in mind that isso expects to have an array, so keep the opening and ending square bracket even if you have only one article thread!

Next you can import you json dump:

~> isso -c /path/to/isso.cfg import -t generic comment-dump.json
[100%]  53 threads, 192 comments

Export comments as CSV

As suggested by Joshua Gleitze:

data=$(sqlite3 ${dbpath} -csv 'SELECT threads.uri, threads.title,, comments.mode, datetime(comments.created, "unixepoch", "localtime"), datetime(comments.modified, "unixepoch", "localtime"),,,, comments.remote_addr, comments.likes, comments.dislikes, comments.voters,comments.text FROM comments INNER JOIN threads ON')
header='"page: URI","page: title","ID","mode","created on","modified on","author: name","author: email","author: website","author: IP","likes","dislikes","voters","text"'
echo -e "${header}\n""${data}" > export.csv

Use and see other options as discussed in this issue.

Pretty-print entire comments database

The following bash function pretty-print the entire comments DB sorted by insertion date.

get_blog_comments () {
    ssh $host sqlite3 -line /path/to/isso/isso.db \
        "'SELECT t.uri,c.created,c.modified,c.text,,, \
          FROM comments AS c, threads as t WHERE c.tid =;'" \
        | perl -wpe '/(created|modified) = ./&&s/= (.*)/"= ".scalar(localtime($1))/e';

Example output:

     uri = /lucas/blog/2014/12/12/fr-la-tete-dans-le-guidon/
 created = Mon Dec 15 13:10:28 2014
modified =
    text = Merci ! Je suis très content d'apprendre que cette lecture a pu plaire à quelqu'un
N'hésitez pas à partager vos propres réflexions et astuces dans les commentaires.
  author = lucas
   email =
 website =

Delete IP addresses weekly

Add this to your crontab to set all saved commenter IP addresses to to preserve their privacy under GDPR:

@weekly /usr/bin/sqlite3 /path/to/isso/comments.db 'UPDATE comments SET remote_addr = "";'


Note that Isso already anonymizes the last part of IP addresses by setting them to to zero.

Change linked comment highlight color

When you click a link that goes to a specific Isso comment (such as, the comment will be highlighted yellow and then fade out over a few seconds.

Add the following CSS to your site to change that color (replace #3f3c1c with any color of your choice):

@keyframes isso-target-fade {
  0% { background-color: #3f3c1c; }


This section of the Isso documentation is incomplete. Please help by expanding it.

Click the Edit on GitHub button in the top right corner and read the GitHub Issue named Improve & Expand Documentation for further information.

What’s missing?

  • Removing unused languages

  • Importing & exporting comments (integrate migration docs)

  • Keeping compat using babel

… and other collected tips & tricks, maybe also from the wiki.