Embed a List of Discourse Topics Into an External Site

Discourse · January 31, 2024, 11:59pm

Embedding a list of Discourse topics on external websites allows you to showcase forum content such as discussions or announcements in a seamless and cohesive manner. This guide will walk you through the process of implementing Discourse topic embeds so you can enrich your blog, website, or external content platform.

How to Embed a List of Topics

To embed a list of Discourse topics into another site, follow these steps:

Enable the embed topics list site setting in your Discourse instance.
In your external website’s HTML, add a <script> tag with the JavaScript necessary for embedding:

<script src="http://yourdiscourseforum.com/javascripts/embed-topics.js"></script>

Make sure to replace yourdiscourseforum.com with the address of your Discourse forum.

In the <body> of your external website’s HTML, add a d-topics-list tag where you’d like to display the topics list:

<d-topics-list discourse-url="http://yourdiscourseforum.com" category="1234" per-page="5"></d-topics-list>

Again, substitute http://yourdiscourseforum.com with your forum URL. You can also use attributes to configure your topics list, such as category, tags, or per-page.

Any additional parameters will convert into query parameters for the topic search. Attributes that contain underscores in their usual Discourse form should be replaced with dashes in the embedding code.

For example, to embed topics based on tags you could use:

<d-topics-list discourse-url="http://yourdiscourseforum.com" tags="cool"></d-topics-list>

The embedded list will update automatically to reflect the most current topics based on the parameters you set.

If the domain you are embedding topics on is different from the domain of the Discourse site hosting the topics, you will need to add the domain you want to embed the topics on to the list of “Embeddings” → “Allowed Hosts” (.../admin/customize/embedding) on the Discourse site hosting the topics.

For example, if your Discourse site located on yourdiscourseforum.com, and you want to embed topics on yourexternalsite.com, you would need to add a record similar to the following to your Discourse forum’s “Embeddings” page:

If you are embedding topics on the same domain as the Discourse site hosting the topics, this step is not necessary.

In SameSite contexts (i.e. the embedding site and your forum share a parent domain), Discourse will know if you’re logged into the forum, and will display the results accordingly. Don’t be surprised if you see secure categories and such when logged in - anonymous users will not be able to!

Due to how topic embeddings function, it is not possible to embed topics from a private login required Discourse site.

List of Parameters

The following parameters can be used in the d-topics-list tag.

template: Choices are complete or basic (default). The complete template displays the topic title, username, avatar, creation date, and thumbnail.
per-page: A number that determines how many topics to display.
category: A number representing the ID of the category whose topics you want to list.
allow-create: A boolean value. When set to true, the embed includes a “New Topic” button.
tags: A string constraining the list to topics with specified tags. You can specify one or multiple tags to filter the topics listed in the embed.
top_period: Options include all, yearly, quarterly, monthly, weekly, daily. If enabled, it will return the “Top” topics for the selected period.

You can combine multiple parameters like category and tags to refine your topics list.

Styling the List

You can style the embed list using custom SCSS in your Discourse’s Embedded CSS theme settings.

The default look of the complete template embed is a plain list, but with custom styling, you can, for instance, transform it into a grid layout.

An example SCSS customization for a grid layout:

.topics-list {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  .topic-list-item {
    .main-link {
      border: 1px dotted gray;
      padding: 0;
    }
    .topic-column-wrapper {
      flex-direction: column-reverse;
      .topic-column.details-column {
        width: 100%;
      }
      .topic-column.featured-image-column .topic-featured-image img {
        max-width: initial;
        max-height: initial;
        width: 100%;
      }
    }
  }
}

This will give the embed list a two-column grid appearance.

For further details about customizing SCSS see:

Example Setup

Below is an example site here where you can see this feature in action:

@Lilly’s Embed Topics Example

You can view the source in your browser to see the code, and the entire source is also on github here: @Lilly’s Embed-Topics Github Repo

Additional Information

Embedded Topics and iframes: The embedded topics list does not use an iframe. It relies on a JavaScript widget that you include on your site using a <script> tag. The usage of the widget allows for a more seamless and integrated experience than an iframe, by allowing customization through CSS and behaving more naturally as part of the webpage’s DOM structure. It is generally not recommended (and often not necessary) to use an iframe for embedding a list of topics from Discourse.

Integration with Comments: It’s also possible enable embedding comments from a Discourse topic onto a separate website using JavaScript. This feature creates an iframe on the remote site to display the Discourse comments. For information on how to setup this up, see: Embed Discourse comments on another website via Javascript

Last edited by @JammyDodger 2024-05-26T06:43:48Z

Check document
Perform check on document:

Michael_Baker · February 11, 2024, 7:19pm

Does this work with Discourse subscriptions? I tried to implement it and it was framing in my whole forum rather than topics?

SaraDev · February 15, 2024, 9:04pm

Yes, this should work alongside the Discourse Subscriptions plugin without any issues.

The embedding relies on configuring specific parameters to control what topics are displayed, such as category, tags, or per-page, through the d-topics-list tag in your website’s HTML. If your embedding ended up framing your whole forum, you might want to make sure that the Discourse URL and any parameters in the <d-topics-list> tag are properly set to reflect the topics you intend to display.

yoke_snowwolf · February 19, 2024, 10:23am

Hi，it’s very nice！Thanks!

I want to change the topic-list-item a element target value to “_blank”（default is _parent，has across domain problem and and it’s not what I want），

what should I do?

Michael_Baker · February 27, 2024, 7:51pm

Hello, I am trying to get these to display on 2 different sites.

My discourse URL is https://learn.getupearlier.com

I have this script embedded here and it’s working:

I have the same script embedded here and it’s not working:

This is in the header:

<script src="https://learn.getupearlier.com/javascripts/embed-topics.js"></script>

This is in the page:

<d-topics-list discourse-url="https://learn.getupearlier.com" category="5" per-page="10"></d-topics-list>

Any help is appreciated!

SaraDev · March 7, 2024, 8:29pm

Hi Michael,

The issue you’re encountering here is likely related to using a domain different from your Discourse domain to embed the topics on.

Your script is working on getupearlier.com because this is on the same domain as your Discourse site learn.getupearlier.com, whereas michaelbakerdigital.com is on a different domain.

I’ve added this section to the guide, which explains how to resolve this situation.

So for your situation, adding michaelbakerdigital.com to your Discourse site’s “Embedding” → “Allowed Hosts” should allow you to correctly embed topics on that domain.

Michael_Baker · May 26, 2024, 10:54pm

Hello I allowed this URL as you can see below:

Here is the test URL:

I just get a blank grey error box

And this is the code inside michaelbakerdigital.com

<div id='discourse-comments'></div>
<meta name='discourse-username' content='MikeB'>

<script type="text/javascript">
  DiscourseEmbed = {
    discourseUrl: 'https://learn.getupearlier.com/',
    discourseEmbedUrl: 'michaelbakerdigital.com',
    // className: 'CLASS_NAME',
  };

  (function() {
    var d = document.createElement('script'); d.type = 'text/javascript'; d.async = true;
    d.src = DiscourseEmbed.discourseUrl + 'javascripts/embed.js';
    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(d);
  })();
</script>

Or this:

<d-topics-list discourse-url="https://learn.getupearlier.com" category="5" per-page="5"></d-topics-list>

Any help appreciated I’ve been stuck here forever and keep meaning to get this solved

Michael_Baker · May 30, 2024, 4:18pm

Hello the solution here was my domain name that was added to the embed section needed www.

That’s it! So much time for 4 characters but solved it with help of Discourse and WP Engine support

Michael_Baker · May 30, 2024, 5:13pm

Is there an example code to use for outputting a featured image as well to the external site?

Thanks so much

pinder99 · June 26, 2024, 6:37pm

Help Needed: Embedding Discourse Topic List on Next.js Site

Hi everyone,

I’m trying to embed a Discourse topic list on my website (example.io) which is built with the Next.js framework and Node.js, deployed through Vercel. I’ve created a test replica of the website on test-discourse.app for this purpose.

Here’s what I’ve done so far:

Added the host to the Discourse embedding settings.
Enabled CORS in the environment and added the host to the CORS origin.
Turned off CSP (Content Security Policy).

Despite following these steps and adding the necessary scripts, I’m still unable to see the topic list on my website.

Here’s the code I’m using:

In the head section:

<script src="my-website/javascripts/embed-topics.js"></script>

In the body section:

<d-topics-list discourse-url="my-website" tags="example"></d-topics-list>

Also tried the categories embed as shown in post

Could anyone point out what I might be missing or doing wrong? Any suggestions to get the topic list to appear on my website would be greatly appreciated.

Thank you in advance for your help!

Topic		Replies	Views
Embedding a list of Discourse Topics in another site announcements embedding	91	20293	February 25, 2024
Embed Discourse comments on another website via Javascript Integrations embedding , how-to	108	292269	June 4, 2024
How can I troubleshoot Discourse comments embedding feature? support	17	4736	June 26, 2015
Embedding, but don't automatically create a topic until a user chooses to comment feature pr-welcome	55	8165	January 21, 2018
"Error Embedding" comments support	16	2109	May 4, 2022