> đź”– 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:
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:
Some notable settings include:
- `post onebox maxlength`: Controls the amount of text included in a onebox
- `max oneboxes per post`: Limits the number of oneboxes that can appear in a single post (default: 50)
- `enable inline onebox on all domains`: Enables inline oneboxes on all domains, converting plain URLs to linked titles (e.g., `https://en.wikipedia.org/wiki/Fun_(band)` becomes “Fun (band) - Wikipedia”). This is enabled by default.
- `blocked onebox domains`: Allows you to disable oneboxes for specific domains
- `block onebox on redirect`: When enabled, prevents oneboxing URLs that redirect to a different destination
## How oneboxes work
When a link is included in a post, Discourse visits the destination page and looks for [Open Graph](http://ogp.me/) or [oEmbed](https://oembed.com/) 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](https://discourse.org) that shows the site title, featured image, icon, and description:
> **[Where Tech Companies Build Communities](https://discourse.org/)**
>
> The customizable, scalable community platform powering over 22,000 communities. Create knowledge through conversation.
## Troubleshooting
If oneboxes aren’t working as expected, try these steps:
1. Test the site using [iFramely](https://iframely.com/embed):
2. Check if the onebox request is being blocked:
3. For internal links not displaying as oneboxes:
From the rails console you can explicitly invalidate/fetch oneboxes by calling [the methods](https://github.com/discourse/discourse/blob/main/lib/oneboxer.rb) while testing by doing:
```plaintext
[1] pry(main)> Oneboxer.invalidate(url)
=> 0
[2] pry(main)> Oneboxer.onebox(url)
=> "