When are link previews shown in Discourse?

Continuing the discussion from NBN honeymoon rates designed to make plan comparison more difficult:

What is the criteria for link previews to be shown in Discourse? In the referenced post link preview wasn’t enabled and funnily enough the link was from choice so you’d think Choice would want the extra awareness.

For OneBox to display a link as a ‘box’, the link must sit in its own line at separate from a paragraph.

For example with its own line (URL only):

Tyis example is with non-related text on the same line as the URL: ABC News (Australian Broadcasting Corporation)

If you want to show the URL itself, put the URL with < URL > like…

I have edited the link you posted in the thread so the URL has its own line to show you that it now appears in a box.


I should also say that if the URL posted is a search result within a URL, it will only appear as …

Repair, replace, refund | ACCC.

within a post. The original URL is:


Some search results may also appear as the full URL as well depending on the URL site coding.

This is the URL display by OneBox for the same page without the search result text…

If you are unsure how it will look, you can use the preview in discourse which shows what the post will look like in a split window as you type. The preview is seen by clicking on the >> at the bottom right of the write post window. To close the preview, click on the << at the same location.


Thanks for the quick and detailed reply.

Escaping formatting characters

You mean like <https://www.abc.net.au> this which gives https://www.abc.net.au.

I’ll return the favour by telling you how to print formatting characters use \ to escape it like so \<https://www.abc.net.au\>

1 Like

Interesting, the quoted text the URL sets back to the URL title/name and overrides the <>.

And yes to your<> question.

Thanks for the format tip. There are many in discourse other than the standard offering in a post.

Also note that the target of the URL needs to contain certain fields (tags), particularly description, for Onebox to do its display.


Discovery of formatting language is in the blank reply to box in grey. Discourse supports Markdown, BBCode and HTML.

Markdown is also used by OzBargain so I’m quite familiar with it’s workings.

It’s been a while though since I used BBCode though.

Yes I’m aware of Schema for a few years now.

1 Like

And, for completeness, if you want to use better linktext in your link than the default text then the syntax is [linktext](url) e.g. ABC News.

Also, if you want a link in the default format on a line by itself but you want to suppress the box then you can precede the URL with a single “invisible” character e.g. a single space character will suffice.

ABC News (Australian Broadcasting Corporation)


That’s part of Markdown Link syntax. It’s not quite complete as you can alter the tool-tip with a quoted word in the between the rounded parenthesis e.g. ABC News. Use the mouse to roll-over the previous link and note the pop up text (“tool-tip”)

And in fact there’s even more related to links

More MarkDown Link Syntax


Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Will produce:

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

If you’re referring to a local resource on the same server, you can use relative paths:

See my [About](/about/) page for details.   

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

This is [an example][id] reference-style link.

You can optionally use a space to separate the sets of brackets:

This is [an example] [id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/  "Optional Title Here"

That is:

  • Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
  • followed by a colon;
  • followed by one or more spaces (or tabs);
  • followed by the URL for the link;
  • optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

[id]: <http://example.com/>  "Optional Title Here"

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation — but they are not case sensitive. E.g. these two links:

[link text][a]
[link text][A]

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word “Google” to the google.com web site, you could simply write:


And then define the link:

[Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

Visit [Daring Fireball][] for more information.

And then define the link:

[Daring Fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here’s an example of reference links in action:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

Using the implicit link name shortcut, you could instead write:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

Both of the above examples will produce the following HTML output:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using Markdown’s inline link style:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.

With Markdown’s reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

1 Like