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 listsite 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 ad-topics-listtag 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.
List of Parameters
The following parameters can be used in the d-topics-list tag.
template: Choices arecompleteorbasic(default). Thecompletetemplate 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 includeall,yearly,quarterly,monthly,weekly,daily. If enabled, it will return the âTopâ topics for the selected period.
categoryandtagsto 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:
- Make CSS changes on Your Site
- Style the embedded Discourse frame on your web page
- Designerâs Guide to getting started with themes in Discourse
Example Setup
Below is an example site here where you can see this feature in action:
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
