Embedding a list of Discourse Topics in another site

If you grab the latest builds of Discourse you’ll get a the ability to embed topic lists in other sites via some simple Javascript and HTML.

The typical use case for this is a blog or other content driven site, where you want a widget on the side of the screen that lists topics. You can filter by category, tag, or any of the other public filter options available.

How to Embed a list of Topics

First, you must enable the embed topics list site setting.

Then, in your HTML add a <script> tag that includes the javascript necessary to embed the Discourse topics. You can add this wherever you normally add scripts. For example:

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

Replace URL with the forum address, including the subfolder if it exists.

After that, in the <body> of your HTML document, add a a tag to indicate the list of topics you’d like to embed. You’ll need to replace URL with your base URL here too:

<d-topics-list discourse-url="URL" category="1234" per-page="5"></d-topics-list>

Any attributes you provide (besides discourse-url which is required) will be converted into the query parameters for the topic search. So if you wanted to search topics by tag you could do this:

<d-topics-list discourse-url="URL" tags="cool"></d-topics-list>

If a query parameter has underscores, convert it to dashes. In the above example, you probably noticed thatper_page became per-page.

Finally it’s worth mentioning that Discourse is smart enough to 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!


I’ve created an example site here:


You should be able to view source in your browser to see the code, but also the entire source is on github:

This is a brand new feature so any feedback / requests would be appreciated.


Here is how it looks:


I should also note that it will use your theme colors too, and the iframe there can be styled via CSS on the host page to be wider if you like.


This looks weird on iOS has it been tested on mobile?

I have not yet, but I strongly suspect in this case it’s related to it being in a nested iframe. I will do a mobile pass tomorrow.


For some reason, I’m struggling to figure out how to do this…

For log in only sites, I can confirm this works. I see all the topics I expect when logged in, and none when I don’t. But when I’m not logged in the result is a bit odd looking:


1 Like

I’ve created an example site here:


You should be able to view source in your browser to see the code, but also the entire source is on github:

(I’m going to add these to the OP shortly.)

I can confirm it works on mobile and the <iframe> resizing I alluded to also works.


That means your server is returning an error. Can you check your server logs for what is happening? I confirmed with the example site I just linked to that anonymous listing of topics works.


I’ll see what errors are in the logs when I can but one detail I may have been more explicit about: our site is log in required.

I’m not surprised that no topics show up (I’d be surprised if they did!)

I would say login required is an unsupported config right now for embedding topics. In the future we might add a nicer error message saying why.


Wauw this is a cool feature. Im not that technically - but if the source for the output is: https://meta.discourse.org/latest.json

You might add options like:

show_username: true/false
show_number_of_replies: true/false
show_time_for_latest:reply: true/false

What I personally would like is the possibility to insert a list like this on my new frontpage for my site:



This is the CSS I added to achieve the same after peeking at the source:

d-topics-list iframe {
    width: 100%;

I do think it’ll make sense to add options or customize the template. The unfortunate thing is it uses server side rendering so we can’t use the same templates as the ember app. However we could approximate the look.

I am working with a Discourse customer now to deploy this feature and I imagine it’ll be getting some tweaks as they try it out.


it’d have a great functionality, especially that one can embed topics in a specific tag. thanks for the feature :+1:

however, looking at the example site, it’s like this:

does this feature work currently?

Also is it possible to use suggested topics as an attribute? I am looking for some random topic list rather than the latest topics in the list.

Yes I just confirmed the example site is working. Perhaps you are running a browser privacy extension or something that is blocking the iframes?

Currently, no. But I suspect we will be adding other filters in the future.