WP Discourse template customization

The WP Discourse plugin uses HTML templates to add markup to Discourse comments for publishing on WordPress and to WordPress posts for publishing on Discourse. The text content of these templates can be customized on the plugin’s options page. To change the structure of a templates requires you to add a function to your theme’s functions.php file This #howto will explain how to do that.

The templates

In the plugin’s code, the templates are static functions that return a mixture of html and template tags.

Available templates:

  • replies_html - the outer wrapper for the comments section
  • no_replies_html - creates a ‘start the discussion’ link that links back to the Discourse forum
  • bad_response_html - displayed when there is a configuration error with Discourse
  • comment_html - formats each comment as a list item
  • participant_html - displays the user avatars for the participants in the topic
  • publish_format_html - used to format the WordPress post for publishing on Discourse

The template code can be found in the html-templates.php file in the the plugin’s github repo

The filters

At the end of each template function, the markup that is about to be output by the function is filtered through a WordPress hook. This makes it possible for a WordPress theme to grab the HTML and alter or replace it, and then return it to the function.

Available filters:

  • discourse_replies_html - filters replies_html
  • discourse_no_replies_html - filters no_replies_html
  • discourse_no_connection_html - filters bad_response_html
  • discourse_comment_html - filters comment_html
  • discourse_participant_html - filters participant_html
  • discourse_publish_format_html - filters publish_format_html

How to use the filters to customize a template

Customizing each of the templates follows the exact same pattern. First, create a function in your theme’s functions.php file to generate the new or altered template:

// Customizes the no_replies_html template.

function my_namespace_no_replies_html( $input ) {


    // The content you want to output goes here.
    // This function just echoes its input, it will be returned unchanged.
    echo $input;

    $output = ob_get_clean();

    return $output;
// Hook into the function from the plugin's code.
add_filter(  'discourse_no_replies_html', 'my_namespace_no_replies_html' );

In the above function, $input is that value that is passed to your function from the wp-discourse no_replies_html() function. The calls to ob_start() and ob_get_clean() are used for output buffering. What output buffering does is store the HTML that is generated by the function in a variable that is then passed to $output with the call to ob_get_clean. Output buffering has to be used for these functions so that the markup’s template tags are returned in a way that allows them to be processed later.

The call to add_filter( 'discourse_no_replies_html', 'my_namespace_no_replies_html' ); is used to hook the plugin’s no_replies_html() function. What ‘hook’ means is that your function will be called from inside the plugin’s no_replies_html() function when it is run. The $input argument that your function takes is passed to it from inside the plugin’s no_replies_html() function.

You can hook into any of plugin’s template functions by adding a call to:

add_filter( 'discourse_filter_name', 'your_function_name' );

Note: replace my_namespace in the example functions with your namespace. It’s a convention used in WordPress to avoid function name collisions.

Template tags

The templates use ‘tags’ to insert information from the database into the markup. You can use these tags in your custom templates.


Add the featured_image to the publish template

The default publish_format_html template returns the markup for the post that is to be published to Discourse. The template has the following template tags available to it: {excerpt}, {blogurl}, {author}, {thumbnail}, {featuredimage}.

The post’s featured image can be added to the template with the {featuredimage} template tag. This can be done in a custom template by copy and pasting the publish_format_html() function from it’s github page, renaming the function by adding a namespace, adding the {featuredimage} template tag, removing the call to apply_filters from the function’s return statement, and then hooking into the new function. Note: you also need to remove the self::get_text_options() statement from the original function.

// Adds the featured image to the post that is published to Discourse.
function my_namespace_publish_format( $input, $post_id ) {
	$post = get_post( $post_id );
    <small>Originally published at: {blogurl}</small><br>
	$featured_image = get_the_post_thumbnail( $post );
	if ( ! empty( $featured_image ) ) {
		echo $featured_image;

	$output = ob_get_clean();

	return $output;

add_filter( 'discourse_publish_format_html', 'my_namespace_publish_format', 10, 2 );

Publish the WordPress post as a onebox on Discourse

This customization will cause the WordPress post to be published as a onebox on your forum.

Before making this customization, check that oneboxes are created on your forum when you add the URL of one of your WordPress posts to Discourse.

function wpdc_custom_publish_format_html( $input, $post_id ) {
	$permalink = get_the_permalink( $post_id );
	echo $permalink;
	$output = ob_get_clean();

	return $output;
add_filter( 'discourse_publish_format_html', 'wpdc_custom_publish_format_html', 10, 2 );

Remove the avatar image from the comments_html template

The default comments_html template displays a user avatar for each comment that is published. If you are publishing many comments on your WordPress site, this will result in many http requests to Discourse to retrieve the avatar images. To remove the avatar image from the template, first copy and paste the code from the github repo into your theme’s functions.php file and rename it. Then, remove the img tag that displays the avatar. Then add a filter hook for your new function by making a call to add_filter() that references the 'discourse_comment_html' hook and your function name. In your new function’s return statement, remove the call to apply_filter that is in the plugin’s comment_html() function.

function my_namespace_comment_html_without_avatar( $input ) {
    <li class="comment even thread-even depth-1">
        <article class="comment-body">
            <footer class="comment-meta">
                <div class="comment-author vcard">
                    <b class="fn"><a href="{topic_url}" rel="external"
                    <span class="says">says:</span><!-- screen reader text -->
                <!-- .comment-author -->
                <div class="comment-metadata">
                    <time pubdate="" datetime="{comment_created_at}">{comment_created_at}</time>
                <!-- .comment-metadata -->
            <!-- .comment-meta -->
            <div class="comment-content">{comment_body}</div>
            <!-- .comment-content -->
        <!-- .comment-body -->
    $output = ob_get_clean();

    return $output;

add_filter( 'discourse_comment_html', 'my_namespace_comment_html_without_avatar' );

Note: the plugin’s template functions are using a static function self::get_text_options() to get text options that have been configured on the plugin’s options page. This function is not available to you in your custom templates. If you are customizing the templates by copying the plugin’s code, be sure to remove these function calls from your templates. A simple approach would be to replace them with the text that you would like to appear in that section.

Remove the ‘participants’ section

This removes the ‘participants’ section from the replies_html template.

function my_namespace_remove_participants_html( $input ) {
    <div id="comments" class="comments-area discourse-comments-area">
        <h2 class="comments-title discourse-comments-title">Notable Replies</h2><!-- Your 'Notable Replies' heading -->
        <ol class="comment-list">{comments}</ol>
        <div class="respond comment-respond">
            <h3 id="reply-title" class="comment-reply-title">
                Continue the discussion at <!-- Your 'Continue the discussion' text -->
                <a href="{topic_url}">
            <p class="more-replies">{more_replies}</p>
    $output = ob_get_clean();

    return $output;
add_filter( 'discourse_replies_html', 'my_namespace_remove_participants_html' );

Look at the source code

To see the HTML that is in each template, and get a list of template tags that can be each template, please look at the html-templates.php source code on github.

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