Metadata Properties, Unfurling and Structured Data Markup

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.

It's possible to override these values and add additional metadata using related content.

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.

Standard Metadata

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 falls back to intro 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!

Overriding Values

The titles, descriptions and image can be overridden using article extras.

The "SEO" article extras can be added to any template extension form and the site framework will recognise the settings and output the updated properties.

The "Document title" field accepts the tokens [articleheading], [subsitetitle] and [subsitename].

For developers with access, the snippet is available from the iCM resources bundle in subversion. The three field names are DOCUMENTTITLE, DOCUMENTDESCRIPTION and DOCUMENTIMAGE.

Adding Additional Properties

You can also relate iCM metadata to your article which will be output in the page source. You could use this feature to add robots "noindex" meta tags to articles to exclude certain pages from search engine crawlers, or to add verification metadata to page heads.

Note that only values from the properties selected in the subsite configuration are output. iCM metadata is used for a wide variety of different functions so outputting all related metadata would not be appropriate.

In the subsite configuration, pick the properties that hold the values you'd like to output:

This article has two metadata values related to it, one from each of the properties above:

They are added to the page source, with the property providing the name and the value the content, like this:

<meta name="robots" content="noindex">
<meta name="Alphabetic Metadata Relations" content="U">

Sitemaps
If you are excluding articles from search crawlers you might also want to exclude them from your sitemap. See "Excluding Articles" in Sitemaps for how to do that.

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>