Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A commenting system for static content using Github as its backend
JavaScript CSS HTML
branch: master

README.adoc

talaria

talaria is a commenting system for static sites, using Github as backend. It supports Gist-, Issue- and commit-based commenting.

You can see talaria in action here.

Overview

talaria identifies content that potentially has comments through a distinct permalink. It then uses that information to interact with the Github API and retrieve any comments.

talaria currently comes with Issue-, Gist- and commit-based comments. Gist and Issue-based comments work roughly as follows:

  1. retrieve a file that provides a mapping of permalink => Gist|Issue Id

  2. iterate over all permalinks and retrieve the comments for the associated Gist|Issue Id

  3. render all comments

  4. display messages for any errors that might have occurred

For commit-based comments the process is roughly as follows:

  1. iterate over all permalinks and extrapolate the path to the file that contains the contents the permalink identifies

  2. retrieve all commits for said files

  3. aggregate all comments for said commits

  4. render the comments

  5. display error messages if necessary

Users can see all comments for each item directly on your site and will get redirected to Github when they click the "Add a comment" button.

Structural assumptions

For talaria to work, it makes a few assumptions about how your content is structured:

  1. commentable content is wrapped in <article> tags.

  2. each <article> contains a distinct permalink that can be used by talaria to extrapolate the file name or gist id.

Here’s a quick example:

<body>
...
<article>
<a class="permalink" href="/2014/02/06/a-blog-post">A blog post!</a>
<p>My awesome unstyled one line blog post :D</p>
</article>
...
</body>

Installation

You can install talaria through bower:

bower install m2w/talaria

Or grab the latest release from Github.

If you manually grab the release (or clone the repo) make sure you run

bower install

Getting started

Let’s see how talaria can be used to add comments to your static site.

For the following, I assume that you installed talaria through bower and are adding it to a Jekyll-powered site.

Initializing talaria

Add <script> tags for jQuery, async.js and talaria. You can also add a <link> to talaria.css or @include talaria.sass. talaria.{css|sass} provides default styling that mirrors the Github styling.

To initialize talaria call talaria.init(CONFIG). Bare minimum example:

talaria.init({REPOSITORY_NAME: 'm2w.github.com', GITHUB_USERNAME: 'm2w'});

Configuring talaria

talaria is designed to be customizable. Here is the full list of currently supported CONFIG properties:

Global settings

PERMALINK_IDENTIFIER

(default a.permalink) valid CSS selector that can be used to identify each content source

PAGINATION_SCHEME

(default /\/page\d+\//) used to automatically expand comments when viewing non-paginated content

CACHE_TIMEOUT

(default 1hr) sets the period (in ms) after which local content is considered stale.

BACKEND

(default talaria.backend.COMMITS) controls the backend used by talaria. Choices are available as properties on the talaria.backend object: COMMITS, GISTS, ISSUES

Commit-backend specific settings

COMMENTABLE_CONTENT_PATH_PREFIX

(default _posts/) relative path-prefix to your content source files

CONTENT_SUFFIX

(default .md) added during path extrapolation

PERMALINK_STYLE

(default /[\.\w\-_:\/]+\/(\d+)\/(\d+)\/(\d+)\/([\w\-\.]+)$/, which matches something along the lines of /:categories/:year/:month/:day/:slug, note the missing extension at the end) controls how talaria resolves filenames from permalinks, you can choose between pretty, date, none or a custom regex. These correspond to the Jekyll defaults, if you choose to provide your own regex please have a look at extrapolatePathFromPermalink to ensure that it will work as you expect it to.

Gist & Issue-backend specific settings

MAPPINGS

URL that points to a JSON file that provides a mapping between permalinks and Gist|Issue IDs. It must follow the following structure:

{:FILENAME: {"id": :GIST|ISSUE_ID, "permalink": :permalink},
 :FILENAME2: {"id": :GIST|ISSUE_ID, "permalink": :permalink}}

Expect this format to change. Take a look at this Rakefile to see how you could go about generating such mappings.

Customizing talaria’s look’n'feel

If you are using the provided talaria.{css|sass} the comments will mostly mirror their counterparts on Github. It is, however, not a complete set of styling directives, so your mileage may vary.

Gotchas

  • When using the commit backend, avoid committing your commentable content along with other files. e.g. if you regenerate your tag subpages after creating a new blog post, these should be two separate commits.

  • Never have multiple commentable content files in the same changeset. e.g. if you update 3 blog posts at once (say you change the spelling for a tag), commit each change file seperately. This ensures there is no comment overlap between posts. It also guarantees that the user will only see the post he planned to comment on while on Github.

  • Avoid committing non-commentable content along with commentable content.

  • The Github API is currently restricted to 60 API calls per hour for unauthenticated users. This means that for commit-based comments your users can retrieve comments for at most 30 entries. This number is lower if you have multiple commits per content source file; it costs 1 additional API request per additional commit (so if you have 3 commits for a the post /2013/03/22/blog-relaunch, talaria actually needs a total of 4 API calls to get all comments). talaria tries to use sessionStorage to reduce the total number of API calls, but users could potentially still run into 403 errors from throtteling, in which case talaria displays a simple error message.

  • talaria appends the comments to each <article>. This is currently not customizable.

Trivia

talaria are the winged sandals worn by Hermes in Greek mythology.

Something went wrong with that request. Please try again.