Embed a List of Discourse Topics Into an External Site

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:

  1. Enable the embed topics list site setting in your Discourse instance.
  2. 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.

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

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

:person_tipping_hand: 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!

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.

:person_tipping_hand: 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:

https://embed.eviltrout.com

You can view the source in your browser to see the code, and the entire source is also on github here: Embed-Topics

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

3 Likes

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

1 Like

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.

2 Likes

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?

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!