Configuring and troubleshooting oneboxes

Documentation Site Management
, ,
1

:bookmark: This guide explains how to configure and troubleshoot oneboxes in Discourse. It covers admin settings, how oneboxes work, and steps to resolve common issues.

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

  1. Go to the Admin panel
  2. Navigate to the site settings section
  3. Search for “onebox”

You’ll see a list of onebox-related settings:

Onebox site settings
Onebox site settings869Ă—1117 119 KB

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)

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

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

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

  3. 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 documentPerform check on document:
2 Likes
2

This is a good resource but seems to fall short

I did this and it returned a one box, it was light on contents but still looked better than a simple url link

Assuming its being light on content is the issue for it not one boxing on my site based on it not meeting this requirement what can be done?

I don’t see a setting to one box sites that don’t have enough content, so then can a site admin be contacted to make a change on their end, if so what needs to be asked?

How does it help solve the issue of not one boxing?

1 Like