Carnival User Guide

Carnival is an unobtrusive, developer-friendly way to add comments to any web site.

Installation is easy. Once you've created a Site , just add the following HTML snippet to the bottom of your page:

<script src=""></script>
  document.addEventListener("DOMContentLoaded", Carnival.init);

By default, a hidden sidebar will be added to any article elements. Within these elements, each p and pre element will receive a small indicator, visible on hover. When clicked, the sidebar will expand, allowing visitors to comment on that specific portion of your article.

Carnival also sends email notifications on replies and provides an RSS feed of recent comments on your Site.

This page itself has Carnival loaded. Feel free to add comments and view-source to see how it works.


Carnival.init accepts an options object with any of the following keys:

Option Default Value Description
enabled true Add Carnival on this page?
article_author "" The Article author. Used in the Comments Feed.
article_selector "article" The CSS selector used to find the Article element.
block_selector ":scope > p, :scope > pre" The CSS selector used to find elements within the Article on which to add comment Threads. When this selector is used, :scope will refer to your Article element.
onNewComment function(comment) { }; A callback invoked whenever comments are inserted in the DOM.

To pass options, you'll need to modify your event handler like so:

document.addEventListener("DOMContentLoaded", function() {
    enabled: true,
    article_author: "",
    article_selector: "article",
    block_selector: ":scope > p, :scope > pre",
    onNewComment: function(comment) { }

Impact on the DOM

Carnival will insert an element to contain the comment threads and form. This new element will be the first child of your Article element and have the class carnival . To support the positioning of this element, Carnival must ensure that your Article element is position: relative .

Carnival will add sibling elements after each commentable block to hold the comment indicator and count. These elements will have the class carnival-comment-indicator .

When comments are opened, Carnival will add a commenting class to your Article element. To make room for itself, Carnival will shift your Article element 150 pixels to the left. It does this by taking the element's current style.left value and setting a new one 150 pixels less. (Soon, you will be able to disable this shift if you want to handle the positioning yourself.)

Comments Feed

Each Site comes with a Comments Feed of the 20 most recent comments for that Site. You can find it at . This is provided so you can implement automation via Zapier or IFTTT .


Carnival is open-source software. You can directly add issues and track its development on GitHub .

You can also email questions and comments to .