This guide explains how to configure and troubleshoot oneboxes in Discourse. It covers admin settings, how oneboxes work, and steps to resolve common issues.
Required user level: Administrator
Oneboxes are rich link previews that users can create in their posts. While users can easily generate these previews, site administrators have additional controls and may need to troubleshoot when links don’t preview as expected.
Admin configuration
To manage onebox settings:
- Go to the Admin panel
- Navigate to the site settings section
- Search for “onebox”
You’ll see a list of onebox-related settings:
Some notable settings include:
-
post onebox maxlength
: Controls the amount of text included in a onebox -
enable inline onebox on all domains
: Enables inline oneboxes, converting plain URLs to linked titles (e.g.,https://en.wikipedia.org/wiki/Fun_(band)
becomes “Fun (band) - Wikipedia”) -
blocked onebox domains
: Allows you to disable oneboxes for specific domains
How oneboxes work
When a link is included in a post, Discourse visits the destination page and looks for Open Graph or oEmbed tags, including:
- Site address
- Title
- Featured image
- Site icon (or favicon)
- Description (mandatory)
- Product price (if relevant)
Discourse requires the description tag to be present and contain enough text to summarize the page. Without this, the target link will not onebox.
Here’s an example onebox for https://discourse.org that shows the site title, featured image, icon, and description:
Troubleshooting
If oneboxes aren’t working as expected, try these steps:
-
Test the site using iFramely:
- Paste the link and check if it’s using correct OpenGraph or oEmbed meta tags
- Ensure the description text is present and adequate
-
Check if the onebox request is being blocked:
- Some hosts may block “unknown” user agents
- Verify that the target website isn’t blocking Discourse’s user agent
-
For internal links not displaying as oneboxes:
- Ensure the link isn’t in a secure category
- Internal links only onebox in public categories or within the same category for security reasons
Additional resources
Last edited by @hugh 2024-07-16T03:27:46Z
Check document
Perform check on document: