WP Discourse plugin installation and setup


(Simon Cossar) #1


From your WordPress dashboard

  1. Visit ‘Plugins > Add New’
  2. Search for ‘WP Discourse’
  3. Activate WP Discourse from your Plugins page

From wordpress.org

  1. Download WP Discourse
  2. Upload the ‘wp-discourse’ directory to your ‘/wp-content/plugins/’ directory
  3. Activate WP Discourse from your Plugins page

With Composer

If you’re using Composer to manage WordPress, add WP-Discourse to your project’s dependencies. Run:

composer require discourse/wp-discourse ~1.3.3

Or manually add it to your composer.json:

  "require": {
    "php": ">=5.4.0",
    "discourse/wp-discourse": "~1.3.3"

Plugin setup

TL;DR install and activate the plugin. Click on the ‘Discourse’ menu item. Read the setting’s descriptions and configure them as you like. Don’t enable SSO unless you have a good reason to do it.


When you activate the plugin a ‘Discourse’ menu item will be added to your WordPress admin menu. Selecting it will bring you to the WP Discourse options page.

The notice at the top of the page will indicate that you are not connected to your Discourse forum. To establish a connection, enter:

  • the URL of your forum into the ‘Discourse URL’ settings field

  • your forum’s API key (the API key for ‘All Users’, found at /admin/api in your forum’s admin section) in the ‘API Key’ settings field

The ‘Publishing username’ setting defaults to ‘system’. Unless you have changed that name on your forum, you can leave the default value, or change it to the username of any admin user on your forum.

The Publishing Username is the default name under which WordPress posts will be published to Discourse. For WordPress users to publish posts to Discourse with their Discourse username, they need to set their Discourse Username on their WordPress profile page. If a user attempts to publish a post to Discourse without having set their Discourse Username, they will be prompted to set it before they publish the post.

Now click the ‘Save Options’ button. If everything is correctly configured, you should see a notice that ‘You are connected to Discourse’ at the top of the page. If you are ever having issues with the plugin’s connection to your forum, navigate to this page and check the connection status notice.

Publishing Settings

Next click on the ‘Publishing’ Settings tab. This section is for configuring how the plugin publishes posts to Discourse.

The Default Discourse Category option sets the default category in which your posts will be published on Discourse. This setting can be overridden for individual posts in the ‘Publish to Discourse’ metabox on the WordPress post-new screen.

The ‘Display Subcategories’ checkbox indicates whether or not you want to your forum’s subcategories to be available as categories that you can publish to from WordPress. You will need to save this setting before subcategories become available in the Default Discourse Category option input.

Use the ‘Force Category Update’ when you have added new categories to your forum and would like them to be available on your WordPress site. Enabling this setting makes a single API call to Discourse to retrieve the Discourse categories. After enabling it, the next time you navigate back to the Commenting tab, you will find the setting disabled.

Select the ‘Use full post content’ setting if you would like to publish full WordPress posts, rather than excerpts, to your Discourse forum. Note: to keep the ‘Show Full Post’ button from appearing under your post on Discourse, you must unselect the ‘embed truncate’ setting on Discourse (found at yourforum.com/admin/site_settings/category/posting.)

If you have not selected the ‘Use Full Post Content’ setting, the ‘Custom excerpt length’ setting will create excerpts of that length to be published to Discourse. You can also manually create excerpts when you create a WordPress post by adding the excerpt to the ‘Excerpt’ meta-box.

Selecting the ‘Auto Publish’ setting will pre-check the ‘Publish to Discourse’ checkbox that appears on the post-new screen for post-types that are to be published to Discourse. This setting can be overridden for individual posts.

The ‘Auto Track Published Topics’ setting is enabled by default. When enabled, the author of a post published to Discourse from WordPress will automatically be ‘Watching’ the topic (they will receive Discourse notifications about every new reply)

The ‘Post Types to Publish’ setting must be set. It defaults to ‘post’, but pages and custom post types may also be selected.

Click the ‘Save Options’ button to save your settings.

Commenting Settings

Next, click on the ‘Commenting’ settings tab. This section is for configuring how Discourse comments are displayed on your WordPress site.

To have Discourse comments show up on your WordPress site, you must select the ‘Use Discourse Comments’ setting.

To also show existing WordPress comments for posts that have also been published to Discourse, select the ‘Show Existing WP Comments’ setting.

If you are showing existing comments, The ‘Existing Comments Heading’ setting will add a heading above the WordPress comments.

The next group of settings, from ‘Max Visible Comments’ to ‘Only Import Moderator-Liked’ (excluding ‘Custom Datetime Format’, which I now see should be moved ) is for configuring which comments from Discourse should be published on your WordPress site. The default values are a reasonable place to start. If you would like to have complete control over which comments are published, select the ‘Only Import Moderator-Liked’ setting. (Note: comments must be liked by a forum moderator, not an admin.)

The ‘Custom Datetime Format’ setting formats the date that is displayed for each Discourse comment that appears on your WordPress site. Start with the default value. If you find you want to change the date format, click on the link in the settings description for details on how to do that.

Click the ‘Save Options’ button to save your settings.

Text Content Settings

Next, click on the ‘Text Content’ settings tab. This section is for configuring the plugin’s user facing text. If you like, you can leave the default values for this setting in place.

If your site is in a language other than English, you can use this section to translate the plugin’s user facing text.

The ‘Discourse Link Text’, ‘Start Discussion Text’, and ‘Continue Discussion Text’ settings work together to create the text for links from your WordPress site to your Discourse form.

As an example, my forum has the title ‘The Constructive Learning Space’. I would like the ‘Start discussion’ link, that occurs under published posts when there are no comments, and the ‘Continue discussion’ link, that occurs under published posts when there are comments, to read:

‘Start the discussion on the Constructive Learning Space


‘Continue the discussion on the Constructive Learning Space

To do that I add the text ‘Constructive Learning Space’ to the ‘Discourse Link Text’ setting, the text ‘Start the discussion on the’ to the ‘Start Discussion Text’ setting, and the text ‘Continue the discussion on the’ to the ‘Continue Discussion Text’ setting.

Webhook Settings

Webhooks can be used to synchronize data between Discourse and WordPress. Webhook support has been added to the WP Discourse plugin in version 1.4.0. For now, the plugin only has one webhook endpoint. It’s used to let the plugin know when a new post has been added to a Discourse topic. Using this webhook is optional. The reason for adding it is to improve the efficiency with which the plugin synchronizes comments with Discourse.

To use the Sync Comment Data webhook, visit the Discourse URL provided in the setting’s description (http://forum.example.com/admin/api/web_hooks.) On that page, click the ‘New Webhook’ button. That will bring you to a page that looks like this:

In the Payload URL field, enter the URL that is provided in the description of the WP Discourse Sync Comment Data field. It will be something like this, except using your WordPress site’s URL: http://wp-discourse.dev/wp-json/wp-discourse/v1/update-topic-content.

Make sure the Content Type field is set to application/json.

In the Secret input, enter a string of text, at least 12 characters long. Then copy this same key into the WP Discourse Webhook Secret Key setting. The plugin will not process webhooks if the secret key is missing, or if it doesn’t match the key supplied on Discourse.

In the ‘Which events should trigger this webhook?’ box, make sure that ‘Post Event’ is selected.

Use the Triggered Categories field if you only publish posts from WordPress to specific categories. That way, your WordPress site will not need to process webhook requests for topics that don’t have an associated Discourse post.

Leave the Check TLS certificate of payload url setting enabled.

Enable the ‘Active’ checkbox, and click create. When the webhook has saved, click the Go to events button.

On WordPress, enable the Sync Comment Data webhook setting. Make sure that you have entered the webhook secret from Discourse into the Webhook Secret Key field. Then save the options.

The Discourse webhook should now be ready to use. You can check it by clicking the webhook’s Ping button (found at /admin/api/web_hooks/:webhook_id/events.) Doing that should return a status code of 200.

Using the Post Event webhook with old posts

For Discourse topics created through the WP Discourse plugin prior to version 1.4.0, the Discourse topic_ids have not been saved on WordPress with their associated WordPress posts. This creates an issue for syncing old posts with Discourse topics. To get around this, posts with the post_type ‘post’ can be associated with Discourse topics by matching them to the topic’s title. You can use this feature by selecting the Match Old Topics option on the WP Discourse Webhooks tab. If you have old posts that are not using the post_type ‘post’ you can match to other post types by hooking into the wpdc_webhook_get_page_by_title_post_type filter and returning the post type you would like to search for. If you would like to search for multiple post types, you can hook into the wpdc_webhook_after_get_page_by_title action. It supplies the topic_title as a parameter. Make sure your function returns either the WordPress post’s id or a \WP_Error object.

SSO Settings

The ‘SSO’ settings tab is for configuring Single Sign On options between WordPress and Discourse.

Note: unless you have a need to either manage the authentication of Discourse users through WordPress, or the authentication of WordPress users through Discourse, you can leave this section alone.

SSO can be configured to either use your WordPress site as the Single Sign On provider for your Discourse forum, or to use your Discourse forum as a Single Sign On provider for your WordPress site. When Discourse is functioning as the SSO provider, your WordPress site will be the SSO ‘client’.

The SSO options page has three sub-tabs: ‘SSO Secret Key’, ‘SSO Provider’, and ‘SSO Client’.

To use your site as either an SSO provider or client, go to the ‘SSO Secret Key’ tab and enter a string of text (numbers, letters, and symbols are all allowed), at least 10 characters long. Use the same rules for creating this as you would to create a strong password.

Now go to your Discourse forum’s admin settings section.

All SSO options on your forum can be found a the URL yourforum.com/admin/site_settings/category/all_results?filter=sso. In the Discourse ‘sso secret’ field, enter the same value as you have set on WordPress for your Secret Key. Click the green arrow to save the value.

WordPress as the SSO Provider

To enable your site to function as the SSO Provider for your forum, click on the ‘SSO Provider’ tab. Select the ‘Enable SSO Provider’ checkbox and save your settings.

Next, go to your forum’s SSO settings:

  • select ‘enable sso’

  • enter the ‘home URL’ of your WordPress site in the ‘sso url’ input (this can be found in the documentation at the top of the WordPress ‘SSO Provider’ tab.)

Save the settings by clicking the green checkmarks that appear beside each setting.

To make sure that SSO is setup correctly, log out of your forum. After logging out, you’ll notice that the Discourse ‘Sign Up’ button no longer appears. Click on the ‘Log In’ button. If you are currently logged in to your WordPress site, you should now be logged into Discourse. If you are not logged in to WordPress, you will be redirected to the WordPress login screen. Log yourself in there, and you should be redirected back to Discourse and logged in.

If your aren’t able to log back in to your Discourse site, there are a few possible things that could have gone wrong. To fix them, you’ll first need to disable SSO on Discourse so that you can get back into your site. Here is how to to that:

Disable SSO Through the Discourse Console:

cd /var/discourse
./launcher enter app
rails c

Login Through the /users/admin-login Path

  • enter the URL in your browser yourforum.com/users/admin-login
  • enter your admin email address
  • wait for the email and follow it’s instructions

If you’re having issues with using WordPress as the SSO provider for your forum, the first things to check are:

  • that the SSO Secret keys set on WordPress and Discourse are the same

  • make sure that you have selected ‘Enable SSO Provider’ on your WordPress site

  • make sure you have entered the correct ‘sso url’ on Discourse.

If your problem persists, create a topic on this forum in the support/wordpress category, and someone will be able to help you.

There are a few advanced features on the ‘SSO Provider’ tab that can be used for automatically creating and logging in Discourse users when they are created/logged in on WordPress. They are fairly well documented in the plugin. If you have any questions about them, create a topic in the support/wordpress category.

Email Verification When WordPress is the SSO Provider

Discourse expects all user’s email addresses to be verified; WordPress doesn’t force users to verify their email address. In a default WordPress setup it is fairly easy to verify a user’s email address during the registration process, but if a site is using a plugin that creates a front end registration form - for example, the registration form that can be added with WooCommerce - the WP Discourse plugin isn’t able to verify the user’s email. In this case, before a WordPress user will be able to login to the forum, they will need to respond to an email verification notice that is sent out by Discourse. The plugin has a couple of filters that can be used to override this behaviour. Take a look at the code, starting here, for details.

WordPress as the SSO Client

To enable your site to function as an SSO Client for Discourse, click on the ‘SSO Client’ tab. Select:

  • ‘Enable SSO Client’

  • ‘Add Login Link’

Now visit your forum at yourforum.com/admin/site_settings/category/all_results?filter=sso. Then:

  • select the ‘enable sso provider’ setting

  • make sure you have added your WordPress Secret Key to the ‘sso secret’ setting

Discourse should now be functioning as a Single Sign On provider for your WordPress site.

Logout of your WordPress site. When you now go to your login page, you should see a ‘Log in with Discourse’ link underneath the login form. Click it. If you’re not currently logged in to Discourse, you’ll be taken to the Discourse login form. Login there, and you’ll be redirected back to the WordPress login page with a notice saying that you need to sync your account with Discourse. Follow the instructions in the notice to link your accounts, and you should now be able to log into your WordPress site through Discourse.

Note: this behaviour only affects users who have existing accounts on both WordPress and Discourse. New WordPress accounts that are created through Discourse SSO will be able to login freely to WordPress the first time the click the ‘Log in with Discourse’ link. To make it easier for users with existing accounts on both your WordPress site and your Discourse forum to login through Discourse, select the ‘Sync Existing Users by Email’ checkbox on the ‘SSO Client’ options tab.

Syncing Discourse logout when using WordPress as either the SSO client or the SSO provider

When SSO is enabled, logout from Discourse can be synced with your WordPress site by adding your site’s home_url with the query parameter request=logout to the Discourse setting ‘logout redirect’. The setting is in the Discourse settings section at /admin/site_settings/category/users.

Here’s an example ‘logout redirect’ URL:


Customizing the plugin's HTML templates

The HTML templates that are used for publishing WordPress posts to Discourse, and displaying Discourse comments on WordPress can be customized. For details on doing this, see the WP Discourse template customization #howto topic.

Publishing Posts to Discourse

The plugin adds a ‘Publish to Discourse’ metabox to the WordPress ‘post-new’ and ‘post-edit’ screens for post-types that you have selected in the plugin’s options. To publish a post, make sure that the ‘Publish post to Discourse’ checkbox is selected, and select the category you wish to publish to from the category options input. If you edit a published post, the new content will be sent to Discourse. It’s currently not possible to change the Discourse category of a post once it’s been published.

Multisite Support

The WP Discourse plugin works with WordPress multisite setups for everything except using WordPress as an SSO Client for your Discourse site.

Using WordPress as the SSO Provider for Discourse is supported for multisite setups.

The plugin has a Multisite Configuration option for the case where one Discourse forum is connected to a network of multiple WordPress. This option is available on the Connection settings tab of the main site of a network. Selecting it allows some of the plugin’s setting to be used over the entire network (all the connection options, the Webhook options, the SSO Secret Key, and Enable SSO setting.) Enabling this setting will create an extra database table that’s used for associating Discourse topic_ids with WordPress blog_ids when posts are published from WordPress to Discourse.

Tips and Tricks

For tips and tricks on customizing the plugin in your theme’s functions.php file see WP Discourse Plugin tips and tricks

SSO Configured but Not Working
Where can I find API key?
Discourse comments are not reflected on Wordpress blog
WP Discourse 1.0.0 release
Disable email verification with SSO and Discobot messages
Announcing v1.0 of WP Discourse
Where can I find API key?
WP Discourse 1.4.0 Release
Wordpress SSO stuck in redirect loop
Javascript for Beginners
How to kick start a community?
(Jay Pfaffman) #2

If you mess something up and get locked out of your Discourse, you can take these steps to disable SSO from the console:

cd /var/discourse
./launcher enter app
rails c

(Simon Cossar) #3

This topic needs to be updated. Can it be converted into a wiki?

(Sam Saffron) #4

Sure, it is wiki now !

(MagnumDopus) #5

Sorry to bother but I cannot figure out how to set an excerpt box as per these instructions:

“You can also manually create excerpts when you create a WordPress post by adding the excerpt to the ‘Excerpt’ meta-box.”

Is an excerpt box a custom field?

(Simon Cossar) #6

No, it’s this:

If you’re not seeing that box on the new-post page, you need to enable it here:

Out of the box, WordPress only supports excerpts for posts, not for pages. If you need to create excerpts for pages, it’s possible to enable them through your theme’s functions.php file by adding some code similar to this:

add_action( 'init', 'my_add_excerpts_to_pages' );
function my_add_excerpts_to_pages() {
     add_post_type_support( 'page', 'excerpt' );

(adamprocter) #7

Updated my plug in and discourse and connection is ok but when I create a new post it doesnt work - log says ?

ActionView::Template::Error (Discourse::InvalidAccess) /var/www/discourse/lib/auth/default_current_user_provider.rb:79:in `current_user'
Job exception: Failed to open TCP connection to api.discourse.org:443 (getaddrinfo: Temporary failure in name resolution)

(adamprocter) #8

I think it has turned out that my users email was not verified and emails on my set up also seem to have stopped working, once I fixed that and verified account it started working.

(misterdude) #9

When using this plugin for an SSO client, it now shows (Untitled) where it previously showed Login with Discourse or Link your account to Discourse. Has anyone else seen this behavior? Recently updated to beta12…don’t recall seeing this behavior before that.

(Simon Cossar) #10

Can you check to make sure that on the wp-discourse options page, on the SSO/SSO Client tab, ‘Add Login Link’ is selected?

Also check on the Text Content tab and make sure the values for ‘External Login Text’, ‘Link Accounts Text’, and ‘Account is Linked Text’ are filled in.

(misterdude) #11

I turned it off and on but it didn’t seem to work.

I always just used the default text, but I’ll try adding in the text fields to see if that works.

(misterdude) #12

It turns out a third party plugin was causing the issue. This has been resolved now.

(Andrew ) #13

1.4.0 27/06/2017

  • Add Discourse webhook endpoint for syncing Discourse topics with WordPress posts
  • Add a multisite configuration option for use when a single Discourse forum is connected to a network of WordPress sites

Would someone be willing to elaborate on the multisite config, and how it relates to SSO client (if at all)? I just upgraded to 1.4.0, and don’t see the new options at the network or individual site level.

Off to play with webhooks while I wait. :slight_smile:

(Simon Cossar) #14

You won’t see those options unless you install the plugin in a multisite setup.

For a multisite setup, it only works with WordPress as the SSO Provider. Using it with WordPress as the SSO client is coming, but it’s not ready yet.

(Andrew ) #15

Thank you, I am running wordpress in multisite, and have been using wp-discourse on the install for about 2 years, so I am interested to see what this changes. Where should I look for the options? If the options don’t appear as expected, I’ll probably have to reinstall the plugin, but I’m hoping I’ve just looked over them.

(Simon Cossar) #16

There’s only one option to select. It should be available at the bottom of the Connection settings tab on the main site of the network. Can you take a look and see if it’s showing up for you? But don’t enable it just yet because of this:

My assumption was that no one had been using the plugin in a multisite setup. The difficulty with using webhooks with the multisite setup is associating a Discourse topic with a WordPress post. To get around this, when the Multisite Configuration option is selected, a database table is now being created that saves the blog_id/topic_id. This is used when the webhook data is received from Discourse to associate a topic with the correct blog. Without having the data in this table, it won’t be possible to update the old posts on your site with a webhook.

Can you describe your multisite setup a little more? Is it one Discourse forum associated with a network of sites?

(Andrew ) #17

It’s running on WP multisite, but I beliiiiieeeeeve only one of the subsites (not the main ID 1 site) has actively used it.

Okay, I do see the multisite config in the main site Connections under the Discourse tab. I had been looking in network admin, and the subsites… didn’t think to check ID 1 settings. The Discourse tab also shows on the other subsites, but without the multisite config checkbox.

I should also say that it’s not a huge deal (for me) if the old comments get unlinked. Basically all it has been doing is pushing the posts from WP to Discourse, but not really syncing the comments. So if this is an opportunity for a clean break from legacy to the new way, I am fine with that. However, I will await your instructions in case it’s not so simple.

WP Discourse 1.4.0 Release
(Simon Cossar) #18

Great! That’s how it should be. If you select the Multisite Configuration option the Connection settings (API key etc.), Webhook options, and Enable SSO options will be set for all your subsites off of the main site. It will also create the database table that’s used to associate posts with blog_ids.

If you don’t select the Multisite Configuration option, those settings can be made individually for each subsite. The best approach to take really depends on how many subsites you have. If you would like to use webhooks and you have 100 subsites, without selecting the Multisite Configuration option, you’d have to setup 100 webhooks. I don’t think that would be a great idea.

It’s quite late where I am. I’ll look at this in the morning and get back to you.

WP Discourse 1.4.0 Release
(Andrew ) #19

The current network is only 10 sites, so it’s not a huge deal. I’m not in a hurry. Sleep!

I guess this is one potential wrinkle. What if I wanted to link 9 sites to Discourse install A, and 1 site to Discourse install B. Would the multisite config interfere with that in a way keeping them separate would not?

(Simon Cossar) #20

Yes, the way it’s setup now, that would be a problem. It’s only for the case of a single forum linked to a network of sites. It looks like it should be quite easy to add a filter to the plugin to allow the multisite configuration to be overridden for specific blog_ids.