Colaua

Version 0.2.dev1

Colaua is a set of Python and JavaScript code intended to augment static HTML pages generated by Nikola with conversations hosted in GNU social. When a new post is published, a new GNU social conversation is created pointing to the post. The conversation itself is included in the post's comment section using JavaScript.

Colaua uses the beautiful Mithril JavaScript framework by Leo Horie for client-side web programming.

Although the full package is developed with Nikola in mind, the JavaScript part of the code may be used independently in any HTML page, whether written manually or generated programmatically as a static or dynamic page.

Rationale

The progressive adoption of static site generators (or SSGs, like Jekyll or Nikola) for blogs has resulted in many sites opting for centralized, mutually incompatible platforms like Disqus to host their comments (i.e. dynamic content). This adds to the recentralization trend that is plaguing the Internet in the latest years. Colaua tries to offer some integration with a decentralized alternative in the form of GNU social (a.k.a. StatusNet), a federated microblogging system.

The basic idea is similar to Las Indias' WP-GNU social WordPress plugin and Tarteka's GNU social link for Jekyll. However, Colaua fetches comments from the GNU social API using JavaScript code running in the browser. This obviates the need for dynamic server code (like PHP), keeping the pages amenable to store in distributed systems like IPFS or ZeroNet.

About the name

The name of this software is a play on the Nikola SSG, which is named after Nikola Tesla. "Colaua" is an informal version of "Nicolaua" (Nicole) used in Valencia and its whereabouts.

El forn de la Colaua was a popular bakery in the town of Sagunt, in Valencia. Pretty surely some good (and gossipy) conversations took place there!

Using Colaua with Nikola

To make your Nikola site use Colaua to show GNU social conversations in posts, you first need to prepare it with some files and settings. If you already have an existing NIKOLA_SITE directory and a COLAUA_SOURCE directory:

1. Site configuration: edit the NIKOLA_SITE/conf.py file and change the COMMENT_SYSTEM to 'colaua'. The value of COMMENT_SYSTEM_ID is irrelevant to Colaua.
2. JavaScript files: copy the COLAUA_SOURCE/js/*.js files to NIKOLA_SITE/files/assets/js/ (create this directory if missing); download http://mithril.js.org/mithril.min.js and place it in the same directory.
3. Template files: copy the COLAUA_SOURCE/nikola/templates/*.tmpl files to NIKOLA_SITE/templates/.
4. Stylesheets: add the contents of the COLAUA_SOURCE/css/colaua.css file to NIKOLA_SITE/files/assets/css/custom.css (create these directory and file if missing). You may customize the provided styles to your liking.

Whenever you want a GNU social conversation to show up in the comments section of a post, please add to its metadata a field like the following one (in reST notation):

.. colaua-url: https://social.example.com/notice/1234

Where the given URL corresponds to the permalink of the first notice in the conversation. Finally, rebuild your site.

This is not implemented yet:

When Colaua is completed, building a Colaua-enabled post should trigger the automatic creation of a GNU social notice that links to the post.

Using Colaua in an HTML page

If you are not a Nikola user, you may still use the JavaScript code directly to include already existing GNU social conversations in HTML pages. Place Mithril's mithril.min.js and Colaua's colaua.js (or some minified version of it if you know how to do that) where they can be served. Include them in your HTML page:

<script src="js/mithril.min.js"></script>
<script src="js/colaua.js"></script>

Then add something like this to the HTML page at the point where you want the conversation to be shown:

<section>
  <h1>Comments</h1>
  <div id="colaua-conversation" data-colaua-url="URL">
    Please enable JavaScript to show comments from
    a GNU social conversation on this topic.
  </div>
</section>

Where URL is the URL of the GNU social conversation you want to include (something like https://social.example.com/notice/1234). You may have a look at the sample HTML and CSS files included with the source.

The colaua-conversation identifier is recognized automatically and the given conversation replaces the content of the indicated element. You can also use several instances of Colaua at different points in the same page using different identifiers. Just call the Colaua.newOnId() JavaScript function on each of them:

Colaua.newOnId('IDENTIFIER1');
Colaua.newOnId('IDENTIFIER2');
Colaua.newOnId('IDENTIFIER3');
...