Gatsby plugin to use Discourse as headless CMS

I made a plugin, not for Discourse but for Gatsby. The plugin sources topic lists from a Discourse installation and transforms into Gatsby nodes. It simplifies using Discourse a headless CMS.

We use it in a project to build a microblog and a calendar that auto updates when new content is added to the forum.

Here is the microblog:

Source: Förenade Inköp - Nyheter / blogg - Förenade Inköp - Food Shift

And, here is the calendar:

Source: Food Shift
Result: (at the bottom)

Hope someone else finds it useful!

npm version npm downloads

gatsby-source-discourse-topic-list helps you source topic lists from the Discourse discussion forum platform and transform it into Gatsby nodes.

In addition to the topic list provided by the Discourse api, the plugin also fetches the raw text for each topic.

Getting Started

  1. Install the package with yarn or npm

yarn add gatsby-source-discourse-topic-list

  1. Add to plugins in your gatsby-config.js
module.exports = {
    plugins: [
            resolve: "gatsby-source-discourse-topic-list",
            options: {
                url: ""
                endPoint: 'top.json',


Name Type Description
url object or string Required. Url of your Discourse installation as a string. If you have two different APIs for development and production, define an object with the keys production and development.
endPoint string Required. Any Discourse API endpoint returning a topic_list.
rootKey string Optional. Name your API.

Example Discourse API endpoints

Latest topics in a category:

options: {
    url: ""
    endPoint: 'c/1.json',

Latest topics in a category, filtered by tag:

options: {
    url: ""
    endPoint: 'tags/c/bug/1/pr-welcome.json',

Top topics in a category:

options: {
    url: ""
    endPoint: 'c/support/6/l/top.json',

See the Discourse API documentation for a full list of endpoints.

Example result

Note the added raw field containing the full unprocessed post topic text.

  "users": [
      "id": 0,
      "username": "string",
      "avatar_template": "string"
  "topic_list": {
    "can_create_topic": true,
    "draft": {},
    "draft_key": "string",
    "draft_sequence": 0,
    "for_period": "string",
    "per_page": 0,
    "topics": [
        "id": 0,
        "title": "string",
        "fancy_title": "string",
        "slug": "string",
        "raw": "The full unprocessed topic text in markdown format", 

Multiple Sources? Multiple Instances!

If you would like to fetch multiple endpoints in your project, just instantiate the plugin multiple times. Just be sure to set a different rootKey for every instance.


This plugin builds on the excellent gatsby-source-custom-api by Andreas Faust. :pray:


Every contribution is very much appreciated.
Feel free to file bugs, feature- and pull-requests.

:heart: If this plugin is helpful for you, star it on GitHub.


This looks nice. Does this work with topics from private categories ? I am talking about the scenario of using discourse as a headless cms.

1 Like

Not currently but that’s a good idea, it wouldn’t be difficult to add. Accessing private content requires authentication. A username and an API key could be added to the Gatsby config.