Search code examples
asciidocasciidoctorantora

How do I set an OG image for a docs page to render on socials (twitter, linkedin, etc)?

We use Antora for our docs, but when I look at the OG image metadata for one of our guides it doesn't show up: https://metatags.io/?url=https%3A%2F%2Fdocs.timefold.ai%2Ffield-service-routing%2Flatest%2Fuser-guide%2Funderstanding-field-service-routing%2Fshift-hours-and-overtime

enter image description here

I want to set the socials OG image per guide. Is there an asciidoc/antora attribute I can set at the top of the adoc file to accomplish that?

[#shiftHoursAndOvertime]
= Shift hours and overtime

Vehicle drivers have shifts ...
Solution

  • If you want to include Open Graph or Twitter Card metadata, you have to customize your theme to include it. Antora's Default UI doesn't include that support, but it's not hard to add.

    If you forked your UI from the Antora Default UI, you'd add almost all required declarations in src/partials/head-meta.hbs.

    To have a page-specific image, you'd need to check for the attribute you want to define in a page and use its value in the template.

    Here's an example of the kind of markup you'd need to add to your theme:

    <meta property="og:title" content="{{page.title}}">
<meta property="og:image" content="{{page.attributes.meta-image}}">
<meta property="og:image:type" content="image/<type>">
<meta property="og:image:width" content="{{page.attributes.meta-image-width}}">
<meta property="og:image:height" content="{{page.attributes.meta-image-height}}">

    In your pages, you would define page attributes like:

    = Document title
:page-meta-image: <url for image>
:page-meta-image-width: <image width>
:page-meta-image-height: <image height>

    If you use conditionals in the template, you'd be able to provide a default image if the page didn't define one. Take a look at the Antora Default UI's src/partials templates for examples of conditionals.