This guide explains how to embed and display a list of Discourse topics on external websites using JavaScript, allowing you to showcase forum content such as discussions or announcements on blogs, websites, or external content platforms.
Required user level: Administrator
Summary
Embedding Discourse topics on external websites enables you to display topic lists from your Discourse forum directly on other sites. This integration helps drive traffic to your forum and keeps your audience engaged with your community content. The embedded topics appear as a JavaScript widget that integrates with your site’s DOM structure, making it easier to customize through CSS.
Enable topic embedding
To set up topic embedding on your external site:
- Navigate to your Discourse admin dashboard and click
site_settings. Search and enable theembed_topics_listsite setting
- Add the embedding script to your external site’s HTML head section:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Replace discourse.example.com with your actual Discourse forum’s URL.
- Place the topics list element where you want to display topics (such as in a blog post or on an individual site page):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- If you’re embedding topics on a different domain than your Discourse site, add your external site’s domain to Admin > Advanced > Embedding > Hosts
For example, if your Discourse site is located at yourdiscourseforum.com and you want to embed topics on yourexternalsite.com, you need to add yourexternalsite.com to your Allowed Hosts list.
You cannot embed topics from a private login-required Discourse site.
Configuration parameters
The d-topics-list element supports the following attributes to customize your topic display:
-
discourse-url- The URL of your Discourse site (required) -
template- Display style options:-
basic(default) - Shows minimal topic information -
complete- Shows title, username, avatar, creation date, and thumbnail
-
-
per-page- Number of topics to display -
category- Category ID to filter topics from a specific category -
tags- Filter topics by specific tags -
allow-create- When set to true, shows a “New Topic” button -
top_period- Show top topics from a specific time period:allyearlyquarterlymonthlyweeklydaily
You can combine multiple parameters to refine your topic list display. For example:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Customizing the appearance
You can style the embedded topics using custom SCSS in your Admin > Customize > Themes > Edit CSS/HTML settings:
Here’s an example SCSS for creating 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%;
}
}
}
}
Best practices
- Use meaningful category and tag filters to display relevant content for your audience
- Set an appropriate
per-pagevalue to avoid overwhelming visitors - Test your embedded topics on different screen sizes to ensure responsive design
- Consider using the
completetemplate for better visual appeal when space permits - Regularly review your Allowed Hosts list to ensure only authorized domains can embed your topics
Common issues and solutions
Topics not displaying on external domain
Issue: The embedded topics appear as a blank or grey box when viewed on an external domain.
Solution: Add the external domain to your Discourse site’s Admin > Customize > Embedding > Allowed Hosts. Make sure to include the correct subdomain (e.g., if your site uses www.example.com, add www.example.com rather than just example.com).
Script loading errors
Issue: The embed script fails to load or returns connection errors.
Solution:
- Verify that the Discourse URL in your script source is correct and accessible
- Check that the
embed_topics_listsite setting is enabled - Ensure your Discourse site is not login-required for public topics
SameSite context behavior
In SameSite contexts where the embedding site and forum share a parent domain, Discourse respects login status and displays results accordingly. Logged-in users may see content from secure categories that anonymous users cannot access.
FAQs
Q: Can I embed topics from a private Discourse site?
A: No, topic embedding only works with public Discourse sites. Private login-required sites cannot be embedded.
Q: Can I embed multiple topic lists on the same page?
A: Yes, you can include multiple <d-topics-list> elements on the same page with different parameters to display various topic collections.
Q: How do I embed topics with featured images?
A: Use the template="complete" parameter in your <d-topics-list> element to display topics with thumbnails and featured images.
Q: Can I change where topic links open?
A: By default, topic links open in the parent window. You can modify this behavior through CSS or JavaScript customization.
Additional resources
Last edited by @jessii 2025-08-25T21:35:05Z
Check document
Perform check on document:
