Content Discoverability

The site frameworks output standard metadata properties in the head of each page. The values of these properties are taken directly from the content of your article.

Unfurling describes the behaviour of link previews when links to your site are shared. Everything you ever wanted to know about unfurling (opens new window) is a good general guide written by the developers at Slack.

Metadata Properties

Without any modification the frameworks output the following:

<meta name="description" content="Summary text">
<meta property="og:type" content="website">
<meta property="og:title" content="A default article - demo">
<meta property="og:description" content="Summary text">
<meta property="og:url" content="https://demo.gossinteractive.com/article/782/A-default-article">
<meta property="og:site_name" content="GOSS Demo">
<meta property="og:image" content="https://demo.gossinteractive.com/image/1/Test-Image-1/opengraph.jpg?m=1466430411000">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="A default article - demo">
<meta name="twitter:description" content="Summary text">
<meta name="twitter:image" content="https://demo.gossinteractive.com/image/1/Test-Image-1/twittercard.jpg?m=1466430411000">
<meta name="twitter:image:alt" content="Test Image 1">

The three description properties use either the article summary or intro text (summary is used if available, if not it falls back to the intro text in the same way as the List template etc).

The title properties follow the format set in your subsite configuration, built from the tokens [articleheading], [subsitetitle] and [subsitename].

The twitter:card property is also set in your subsite configuration. You can choose between X's two card types: content="summary" or content="summary_large_image". This property isn't only used by X, other platforms like Slack also use it when generating their unfurls.

Images

The various image properties provide details of the first image related to the article. If there isn't a related image your website logo will be used.

Most social platforms that perform unfurling recommend an image that has roughly a 1.9:1 aspect ratio, so we have set the og:image at 1200x630. The twitter:image we generate is 600x600.

To cater for the various sizes, we've found it best to create three variants of your website logo. If you're unsure about variants, this short video shows the three used by this site (turn on the captions too).

You can see the variants that the framework has generated for this site:

• https://docs.gossinteractive.com/image/6606/New-Docs-Logo/logo.png
• https://docs.gossinteractive.com/image/6606/New-Docs-Logo/opengraph.png
• https://docs.gossinteractive.com/image/6606/New-Docs-Logo/twittercard.png

There doesn't seem to be a hard and fast rule about which one will be used. At the time of writing, links in Teams use the Twitter image, sometimes X uses the Open Graph image, and Slack uses the twitter:card tag to decide what sort of unfurl it performs, but then uses the og:image in the preview!

Structured Data Markup

The framework outputs JSON-LD markup in the page source. This is generated automatically from your page content.

Here's the markup for this page:

<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "WebPage",
        "name": "Metadata Properties, Unfurling and Structured Data Markup - The Digital Platform Documentation Site",
        "description": "The metadata properties output by the site frameworks, how to override them, and how your site will appear when links to it are shared.",
        "url": "https://docs.gossinteractive.com/article/7500/Metadata-Properties-Unfurling-and-Structured-Data-Markup",
        "image": {
            "@type": "imageObject",
            "contentUrl": "https://docs.gossinteractive.com/image/6606/New-Docs-Logo/jsonld.png?m=1710517240530",
            "width": 1200,
            "height": 630,
            "caption": "The GOSS Documentation Site"
        }
    }
</script>