A brand new

Erlend Sogge Heggen April 12, 2017

This week we unveiled a completely revamped!

When our original website was first launched in 2013, Discourse’s features were quite novel. Concepts like “infinite scrolling”, “dynamic notifications” and “mobile-friendly” were state of the art for open source community platforms, especially stuck-in-90s era forum software. Now these features are taken for granted, as they should be.

That doesn’t mean we’ve stopped innovating; just look at our latest v1.7 release. But we no longer have to convince people that Discourse is modern, hip – dare I say radical – and keeping with the times. That’s a given. What we need to do now is explain …

What problem can Discourse solve for YOU?

It all started with a new topic

We use Discourse for our own internal team discussions — naturally! Almost a year ago I created a new topic titled “Proposal for a redesigned front page”. It included this mockup:

We all agreed that this needed to happen, just not right away. During the months that followed we sporadically followed up with examples of websites we liked or good sources of inspiration, like this one:

2017 came around and we decided it was time to get the wheels rolling. We went back and forth on the copywriting, which in hindsight is something I should have put much more emphasis on in the first place! My original mockup was all about revising our current copy. We ultimately settled on three “pillars”:

  1. Emails don’t scale.
  2. Problem solving is best done in public.
  3. Communities ought to be owned by their creators.

At this point we brought in web developer extraordinaire Kris Aubuchon to push this project to the finish line. Before long, a shiny new was just waiting for us to flip the switch, which we’ve now done!

If you like our new pitch, consider trusting us with the stewardship of your community: Check out our hosting plans, and then pop on over to and join us in celebrating this shiny new place we call home.


Moving from Facebook Groups to Discourse

Erlend Sogge Heggen March 11, 2017

The following is a guest post by Martin Eriksson @meriksson

On January 4th 2017, the news aggregation site completed its migration from private Facebook Groups to a private Discourse community.

Why the move?

We used to have about 20 Facebook groups for people involved in a network of alternative media projects. Some of the groups were dedicated to editorial discussions, some were general discussion groups for our paying members, some were interest groups about financial issues, gaming, cultural topics etc.

We started using Facebook since it was very easy but we were never comfortable with it. As our network grew and the groups become more numerous and active we become more and more worried about key parts of our infrastructure being under the control of a third-party. If we lost access to our groups it would have caused massive problems for us, including potentially decreasing revenues.

In particular, we were worried since Facebook has increasingly been shutting down not only public pages but also private groups – at least, so we have heard. Since our project has to do with non-mainstream politics and activism, we did not want to take any risks with possible future purges of groups perceived to promote subversive ideas.

Another recurring problem for us was being unable to bring new participants into the project due to them not being Facebook users. One typical case was someone being interested in becoming one of our volunteer editors, but being rejected due to not being able to follow the crucial editorial discussions in the Facebook group for editors. Another, and increasingly costly, problem was people being reluctant to sign up as paying members since our community forum was based on a platform they did not want to use.

After making the move, we have indeed seen an influx of new editors as well as paying members. And not least, we now have people making good contributions to discussions who previously supported the project financially but was on the outside of the social parts of it. Dozens of people actually created Facebook accounts, or reopened previously closed accounts, for the sole reason of accessing our groups. This was something I was personally very ashamed of. Happily, many of these and others as well are now shutting down their accounts or drastically decreasing their activity level on Facebook.

How we made it happen

When we began the migration project I started to look around for ready-made scripts for exporting from Facebook and importing to Discourse. I found one but it was rather rudimentary or experimental. So I realized that we would have to develop a solution ourselves. Luckily I happen to have a background as a Ruby programmer so in part it was a fun and stimulating project for me. And having the existing basic script as a starting point made it really easy to get started.

Some of the major obstacles were working with undocumented aspects of the Facebook API – it turns out that there are many! For example, it was often impossible to access particular objects without any explanation given. In part I had to work by trial and error to figure out how things worked. There are also inconsistencies, most of which are noted in the importer description.

Besides purely technical problems we had to think carefully about how our 20 existing groups could be mapped to the Discourse model. Should we use one Discourse instance or multiple ones? We considered having one Discourse instance per language (we have two languages in daily use among members) and also having one for the editors who run the core projects and one for our community of paying members (readers, podcast listeners etc).

In the end we decided to go for one single Discourse for all groups and instead created an intricate system of categories. One of the reasons for this was to enable searching through all the material instead of forcing users to search on multiple sites. In hindsight this was certainly a good decision, but it created some problems due to the Discourse model being – according to my personal impressions – more oriented toward relatively open forums rather than rigorously segmented ones.

Each Facebook group was imported to a single category to begin with, but since Discourse gives us so much more flexibility than Facebook we could then immediately begin restructuring things. A couple of weeks later we had about 40 categories and more than 10 groups to control access to them. One of the primary groups gives access to about half the categories. This is the group for our paying members who get access to a large number of discussion groups – previously this was very complicated to maintain as a set of Facebook groups, since new members needed to be added individually to each group and we did not know what groups they were interested in. Using categories and groups in Discourse makes it much easier.

We are not done reorganizing all our imported topics in the new categories; a handful of moderators are working on it but we still have more than 2,000 topics in a non-specific category. As more topics get organized, the forum becomes better and better. However, since Discourse is not really intended to be used like this (i.e. doing intricate manipulations of historical content) we also have a number of quirks still be being worked out. We’re actively engaged with the community, discussing our issues in some new, some existing topics.

The perks of a Discourse Community

  • People do not need to have Facebook accounts to be active in the community.

  • Search works really well in Discourse (except for being limited to 50 results per query). The search feature in Facebook groups is badly crippled. It seems Facebook wants to steer users away from discovering old threads and instead get them to start new ones. This breaks up interesting discussions in ways that are very bad for exchanging ideas, including as many users as possible, having long-running discussions etc. Needless to say, if you have multiple Facebook groups, there is no way of making one search query for all of them. Moving to Discourse has given new life to thousands of threads which have high-quality content but was previously in effect hidden by Facebook.

  • The Discourse model for threads, replies, quoting etc is a far superior way of structuring conversations. This really comes down to Discourse having a very good and thought-through model whereas Facebook optimizes for entirely different things than serious discussions. It took some time for people to get used to quoting but by now discussions are much easier to follow.

  • Access management through Discourse groups and categories is far more convenient than managing membership in Facebook groups. Also, SSO integration removes the need for adding and removing people for groups. Once members pay the membership fee and get accounts on our site, they can access the forum without someone needing to add them to groups, figure out which of our groups they are likely to want access to etc.

  • The category system in Discourse makes it a lot easier to create a customized structure, it can be changed easily later on if we change our thinking about it etc. In practice, the forum feels much more like our own which creates an atmosphere if familiarity and trust. Along the same lines, all the detailed customization options makes it feel much more like a true home for our project, rather than some space we borrowed from someone.

  • Mail notifications are way better, from customizable levels of following/watching to summary emails. Related to this, tagging works very well and we can for example ping an entire group (normally generating mail notifications to each person). On Facebook we used tagging a lot but it was very cumbersome and time-consuming and there are several limits (only 50 users can be tagged per post/comment, there is an additional limits on how many tags a particular user can create per day – of course, Discourse also has such limits, but we can customize them ourselves).

  • Activity statistics are great for managing a community, both for admins to keep track and for users to see how their engagement compares to other users. Facebook has nothing similar to this. There is a tool called Grytics which can do similar things but it is cumbersome to use and in any case inferior to the built-in Discourse tools. After importing all our historical Facebook data into Discourse it was amazing to be able to see aggregate statistics on e.g. total number of likes received and other per-user breakdowns.

Many thanks to Martin Eriksson @meriksson for not only sharing his migration experience, but also the code used to accomplish it, which is shared freely on GitHub.


Discourse API Documentation Released!

Blake Erickson March 6, 2017

Today we would like to announce our much anticipated Official API Docs!

You can find them at:

Today, more than ever, an application needs to be able to integrate with other applications and the Discourse API allows you to easily integrate your Discourse forum with any other application. We do have a Ruby based API client, but your company or server might not support Ruby, so our documentation can easily be used to write an integration in any programming language through simple HTTP REST calls.

To aid in integrating with the Discourse API there are Postman files that you can import into your Postman app so that you can easily make API calls. Postman is a great tool that allows you to make API requests and see the HTTP status codes and responses. It can be a lot friendlier to use instead of a command line tool like cURL. Here is a demo:

What can you do with the API?

Anything you want! Because Discourse is a JavaScript application (with a Rails backend), we consume our own API, so anything the web application does your API integration can do as well.

You can use the API to manage all aspects of users like creating new user accounts, suspending a user, logging off a user, and assign roles to a user.

You can also create and respond to topics, gather stats about users, send private messages, upload files, and pretty much anything else you can think of.

Discourse also has support for webhooks! This means that Discourse will send a POST request to an endpoint you specify every time an event triggers such as a new topic, new post, or a new user is created. This means that if you wanted to be notified every time someone mentions a specific keyword you wouldn’t have to poll Discourse every X minutes, but instead could just listen for the webhook event. Your app could then parse the topic and then use the API to send you a personal message in Discourse notifying you that keyword was used.

Contributors Welcome

The Discourse API Docs are of course open source and so contributions are more than welcome. If you find a bug, an un-documented endpoint, or anything else please feel free open a pull request following the contributing instructions.