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

You can find the plugin at WP Discourse – WordPress plugin | 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 items, which are along the left in the dashboard, and at top right in the post editor. Read the setting’s descriptions and configure them as you like. Don’t enable DiscourseConnect 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, the first place to start debugging the issue is to navigate to the plugin’s Connection Options page. If you are not seeing the “You are connected to Discourse” notice, make sure that all settings on this page are valid.

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.

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

DiscourseConnect Settings

The DiscourseConnect settings tab is for configuring DiscourseConnect 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.

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

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

To use your site as either an DiscourseConnect provider or client, go to the DiscourseConnect 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 DiscourseConnect Provider

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

Next, go to your forum’s Admin / Settings page and enter ‘discourse connect’ into the search box to see all your Discourse DiscourseConnect settings.

On Discourse:

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

To make sure that DiscourseConnect 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 DiscourseConnect on Discourse so that you can get back into your site. Here is how to to that:

Disable DiscourseConnect Through the Discourse Console:

cd /var/discourse
./launcher enter app
rails c
SiteSetting.enable_discourse_connect=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 DiscourseConnect provider for your forum, the first things to check are:

  • that the DiscourseConnect Secret keys set on WordPress and Discourse are the same
  • make sure that you have selected Enable DiscourseConnect Provider on your WordPress site
  • make sure you have entered the correct ‘discourse connect url’ on Discourse.

Email Verification When WordPress is the DiscourseConnect 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 DiscourseConnect issues.

20%20AM

WordPress as the DiscourseConnect Client

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

Now go to your Discourse Admin / Settings page and search for ‘discourse connect’ to see all your DiscourseConnect options.

  • select the ‘enable discourse connect provider’ setting
  • copy your DiscourseConnect Secret Key from WordPress to the ‘secret’ field of the Discourse ‘discourse connect provider secrets’ setting. In that setting’s ‘domain’ field enter your WordPress site’s domain. Then click the green checkmark to save your settings. When complete, the ‘discourse connect provider secrets’ setting on Discourse should look like this (with the domain set to your WordPress domain):

Discourse should now be functioning as a DiscourseConnect 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 DiscourseConnect 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 DiscourseConnect Client’ options tab.

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

When DiscourseConnect 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 DiscourseConnect Client for your Discourse site.

Using WordPress as the DiscourseConnect 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 DiscourseConnect Secret Key, and Enable DiscourseConnect 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.

Logging

The WP Discourse plugin has its own logging system. For more details on the system and how to use it, please see

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

31 Likes
Discourse comments are not reflected on Wordpress blog
Where can I find API key?
SSO Configured but Not Working
How to kick start a community?
WP Discourse 1.0.0 release
WP Discourse 1.4.0 Release
DiscourseConnect - Official Single-Sign-On for Discourse (sso)
Embedding Discourse to wordpress
Api key for activate
Possible to create a news site with pics and videos
Discourse Support Advocate
Wordpress Multisite with Multiple Discourse Instances
Embedding Topic topic-map or Topic Summary on Other Site
Discourse Support Advocate
Discourse member login on Wordpress home page
Calling out for volunteer Community Managers :mega:
Wordpress register with discourse
Basic forum access/integration with Wordpress site
Can my Wordpress members automatically become members of Discourse?
Can it be done with CSS? Grouping categories on category page
Quick Question about Programmatic Link to Existing Topic
Discourse+woocoomerce subscription
Open WP as a subdomain of Discourse (different hostings, only DNS pointing)
Wordpress SSO stuck in redirect loop
Integration with wordpress
Discourse Support Advocate
Where can I find API key?
Update group membership using external database
Switching to Discourse Subscriptions from WordPress Subscriptions
How to connect my wordpress site to discourse forum
WordPress SSO + Normal User registration?
Create users - SSO
Create users - SSO
OAuth 2 and other discourse sites?
Migrate WordPress Comments to Discourse
Deactivate auto publish discourse to post wordpress
Managing Subscriptions through Wordpress (Ultimate Member + Paid Memberships Pro)
Error Log Missing
How does Discourse work with WordPress sites?
Landing Pages Blog :small_airplane:
Discourse Support Advocate
DiscourseConnect Won't Let Me Log Back In
Discourse Support Advocate
Announcing v1.0 of WP Discourse
DiscourseConnect Won't Let Me Log Back In
Disable posting wordpress articles to Discourse when they're updated
Wordpress plugin not redirect to discourse login automatically
Option to publish posts to Discourse not showing up
How to use same wordpress`s user database for discourse forum?
Wanting to start a closed community... should I Require Approval or Invite-only?
Discourse Support Advocate
Discourse Support Advocate
Posts and pages aren't uploading from WP discourse plugin
Discourse Support Advocate
Is it possible to authenticate a Wordpress login via Discourse?
Does a social login WP plugin address Discourse expectation for email verification? (with WP as SSO provider)
WordPress in a Discourse iFrame?
Managing Discourse group membership with WP Discourse SSO
WordPress Integration Questions
Protecting Discourse
Does discourse have discourse integration with wordpress in video