WP Discourse plugin installation and setup

Installation

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.6.1

Or manually add it to your composer.json:

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

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.

Connection

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.

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 on the WordPress post-new screen.

The Display Subcategories checkbox indicates whether or not you want 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.

Enable the Force Category Update option when you have added new categories to your forum and would like them to be available on your WordPress site. Enabling this setting and saving the options page 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.

Enable Allow Tags if you would like to add tags to Discourse topics that are created via WordPress.

Publish as Unlisted Topics will cause posts published from WordPress to be Unlisted on Discourse. If you enable the Sync Comment Data webhook setting, unlisted posts will be made visible when they first receive a reply on Discourse.

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.

When using the WordPress Classic Editor, 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. This setting does not mark posts to be automatically published when the WordPress Block Editor is used to publish 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 Enable Discourse Comments setting. When enabled, you will see two options. The Display comments option will load a Comment template for each WordPress post that has been published to Discourse. This template will display Discourse comments beneath the WordPress posts. The Display a link to the comments option will load a comments template that displays a link to the associated Discourse topic underneath the published posts. The number of replies to the topic will be displayed in the link, but no replies will be displayed on WordPress.

Both of these commenting options work by loading comment templates for the WordPress posts. This means that they will only work if comments are enabled for the post. If you would like to enable comments for all posts, but not have any historical WordPress comments be displayed for posts that have not been published to Discourse, enable the Remove WordPress Comments Template setting.

The Load Comments With Ajax setting is used to load comments from the client, instead of loading them from the server. This is useful if page caching is preventing fresh comments from being loaded on your site.

The Load Comment CSS setting loads a stylesheet that fixes issues with Discourse oneboxes and quotes when they are displayed on WordPress.

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 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 setting’s 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 “Simon’s Demo Forum”. 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 Simon’s Demo Forum

and

Continue the discussion on Simon’s Demo Forum

To do that I add the text “Simon’s Demo Forum” to the Discourse Link Text setting, the text 'Start the discussion on ’ to the Start Discussion Text setting, and the text 'Continue the discussion on ’ to the Continue Discussion Text setting.

The three settings that are prefixed with Join Discussion Link: are for when the ‘Join Discussion’ link is being used instead of displaying Discourse comments. The no Comments link is the text that will be displayed before any comments have been added to the Discourse topic. After that, the Comments Singular and Comments Plural text will be used. The number of comments will be prepended to the text for each of these settings.

Webhook Settings

Webhooks can be used to synchronize data between Discourse and WordPress.

Enabling the Sync Comment Data wehbook can greatly reduce the number of API requests made from WordPress to Discourse.

The Update Userdata webhook is only used when WordPress is configured as the SSO Provider for your Discourse site. The Update Userdata webhook automatically fills in the user’s Discourse Name field on WordPress. This webhook exists for historical reasons - having the Discourse Name field automatically filled in can now be accomplished by using the Create or Sync Discourse Users on Login SSO Provider option.

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: https://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…

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 should check it by clicking the webhook’s Ping button on Discourse (found at /admin/api/web_hooks/:webhook_id/events.) Make sure that pinging the webhook is returning a status code of 200.

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 click the ‘Save Options’ button.

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 Admin / Settings page and enter ‘sso’ into the search box to see all your Discourse SSO settings.

On Discourse:

  • select ‘enable sso’
  • enter the home URL of your WordPress site in the ‘sso url’ input (your WordPress home URL can be found in the description at the top of the WP Discourse SSO Provider settings page.)
  • copy your SSO Secret Key from WordPress to the Discourse ‘sso secret’ setting.

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
SiteSetting.enable_sso=false
exit
exit

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.

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.

If users are getting the following error message when they attempt to login to Discourse, please see Debugging and fixing common SSO issues.

20%20AM

WordPress as the SSO Client

To enable your site to function as an SSO Client for Discourse, click on the SSO Client tab. On that page, select the Enable SSO Client and Add Login Link options.

Now go to your Discourse Admin / Settings page and search for ‘sso’ to see all your SSO options.

  • select the ‘enable sso provider’ setting
  • copy your SSO Secret Key from WordPress to the ‘secret’ field of the Discourse ‘sso provider secrets’ setting. In that setting’s ‘domain’ field enter *. Then click the green checkmark to save your settings. When complete, the ‘sso provider secrets’ setting on Discourse should look like this:

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:

http://example.com/?request=logout

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 settings 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

22 Likes

11 posts were split to a new topic: WordPress as SSO Client in a Multisite Installation

A post was split to a new topic: Value of integrating Discourse and WordPress

5 posts were merged into an existing topic: Link existing forum topic to new WordPress post

4 posts were split to a new topic: Confirming Discourse username when publishing posts from WordPress

4 posts were split to a new topic: Only Import Moderator Liked setting hides moderator’s posts

6 posts were split to a new topic: Move the Discourse Username field out of WordPress Contact Info section

A post was split to a new topic: Allow publishing unlisted topics to be configured by category

A post was merged into an existing topic: WP Discourse Plugin Tips and Tricks

On another topic, I’ll share a little thing :

On a wordpress running for a few years, I had trouble to connect Discourse and Wordpress. I had the error message “You are not connected to Discourse. If you are setting up the plugin, this notice should go away after completing the form on this page.” even though everything was correct.

It is a wordpress on a shared hosting plan and it was stuck on a old version of php (5.4 if I remember correctly). I upgraded php via the hosting service (php 7.0 stable version), since then the connection works perfectly.

It was this topic who helped me identify the issue : Wordpress failure to connect to Discourse
curl wasn’t up to date before my php upgrade

The SSO Provider stuff worked before that, so it probably wasn’t a big deal, but this bugged me.

I lost too many time on this, so I wanted to share with others who might have this issue.

5 Likes

All working great now.

While i’m here, is it possible to include the title with the excerpt? and/or the header photo? i think that extra content would increase people clicking through to read the full article

Probably the easiest way to do what you are looking for is to customize the discourse_publish_format_html template so that it published the post as a onebox. Have a look at WP Discourse template customization for details about how to do that.

3 Likes

NM. seems my php process needed to be restarted(agressive caching settings) because my plugin changes. If anyone have problems with empty fields in the discourse connection tab.

Hey! I am not using Discourse right now and I am looking can I use it or not for my case.
Some questions for it:

  1. Can WP Discourse work with some WP sites as SSO auth center and as comments. For example I have 3 WP websites in similar subject (about cats, about dogs and about pet food) and I want make one forum (about pets) for single SSO point, for comments, etc…

  2. Can I use simple modal window (or pop up) for user auth on my websites without redirect to forum domain when user want to login or register account. I thinking redirect will frustrate users. They not interesting how I keep userbase they don’t want excess redirect without reasons. Redirect to other domain/website scare a lot of people.

Thx for your time

If you set discourse as the SSO master then people will be redirected there when they log in. For a number of reasons they need to know what site they are logging in to.

I don’t think so. Website can say information about common account like “Do you know, we have other thematic websites cats.example.com and dogs.example.com and you can talk on our great forum-pets.example.com without additional registration?”. This is a good way. Bad way is redirect user to extraneous website without any explanation.