Embedding Discourse in Static Sites

Jan 22 2014

It’s been possible to embed comments from a Discourse forum on to other sites for a while now, but the only publishing software we supported was Wordpress.

Many people, myself included, don’t use Wordpress to run their sites. This very blog is a series of static HTML documents that are generated by Middleman. (Like Discourse itself, my blog is open source; you can find the code here so feel free to submit pull requests!).

Well… Good News Everyone! It’s now possible to embed Discourse content into any HTML document. In fact, as you can see below, the comments on this very site are now handled by a Discourse instance I set up.

How it Works

You can now configure Discourse to support embedding. Once you’ve done that, you paste a small snippet of Javascript into your site template and you’re off to the races.

Discourse will create topics for your blog entries if you provide it with an RSS or Atom feed. It’s also smart enough to update them if the content changes, say for corrections or typos. When any users of your forum post comments, they will automatically be inserted into your blog.

If your site does not have an XML feed, Discourse will create topics based on your page contents using a readability algorithm. It’s remarkably accurate for those cases when your site doesn’t have a feed.

How to Set up Embedding

  1. Install a Discourse Forum. We currently recommend using discourse_docker to do this. If you have ruby on your computer, you can even do it via a command line wizard.

  2. Navigate to the Embedding Site Settings. The URL will be something like:

    http://discourse.yourdomain.com/admin/site_settings/category/embedding

  3. Configure the settings appropriately. Here’s how it looks for my blog:

    Embedding Settings

  4. In your blog template, paste in the following snippet of Javascript and a <div> tag for where you’d like the comments to appear:

    <div id="discourse-comments"></div>
    
    <script type="text/javascript">
      var discourseUrl = "http://fishtank.eviltrout.com/",
          discourseEmbedUrl = 'http://eviltrout.com/link-to-blog-entry.html';
    
      (function() {
        var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
          d.src = discourseUrl + 'javascripts/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
      })();
    </script>
    

    Configuration

    1. You will have to change the discourseUrl variable so it points to the root URL of your Discourse forum.
    2. Make sure discourseEmbedUrl is the canonical URL to the page where you are embedding Discourse. You will want to make sure this uniquely identifies the page. For my blog template, I use the following code to link to the article: discourseEmbedUrl = 'http://eviltrout.com<%= current_page.url %>'

  5. Reload your blog. Your blog posts should start syncing over to your forum and any comments should be imported into your blog. It’s that easy!

Going Forward

eviltrout.com has been running this set up for a few weeks now and it’s been great! Of course, like with any new feature of Discourse we’d love to hear your feedback so we can iterate on it and make it better. Let us know how it works for your use case.

I'm in New York City offering Ember.js training with Erik Bryn on May 22 & 23. Learn more!