Add Open Graph Support

[Kyle-Ye]

Feature Name

Add Open Graph Support

Description

Currently when sharing a documentation(Article or Tutorial), the url is render as a pure title card.

If there is image information available, we should add og:image to html header to better render the doc link in other site.

eg. Metadata directive's PageImage parameter

https://forums.swift.org/t/feature-suggestion-add-open-graph-support/65989

[mportiz08]

This may actually require work in the Swift-DocC compiler to fully resolve issues where this data is not being rendered appropriately.

Technically, Swift-DocC-Render already renders some basic open graph metadata (source), but it only does client-side rendering, which is why it may not always work as expected depending on how the page is shared.

We would need to update DocC to add the related meta tags to individual HTML files that it generates for static file hosting solutions like GitHub Pages where there is no server-side logic that could do this.

[Kyle-Ye]

This may actually require work in the Swift-DocC compiler to fully resolve issues where this data is not being rendered appropriately.

Filed an issue on swift-docc to track this. apple/swift-docc#658

We would need to update DocC to add the related meta tags to individual HTML files that it generates for static file hosting solutions like GitHub Pages where there is no server-side logic that could do this.

Got it.

[Kyle-Ye]

We would need to update DocC to add the related meta tags to individual HTML files that it generates for static file hosting solutions like GitHub Pages where there is no server-side logic that could do this.

Taking WWDC23's demo project - SlothCreator as an example. The generated gettingstarted.json from

// GettingStarted.md
@Metadata {
    @PageImage(purpose: card, source: "gettingStarted-card", alt: "The profile images for a regular sloth and an ice sloth.")
}

will be

{
  ...
  "kind": "article",
  "metadata": {
    "images": [
      {
        "identifier": "gettingStarted-card.png",
        "type": "card"
      }
    ],
    "modules": [
      {
        "name": "SlothCreator"
      }
    ],
    "role": "article",
    "roleHeading": "Article",
    "title": "Getting Started with Sloths"
  },
  ...

So I think there is already enough information provided by swift-docc.

We can update the logic from metadata.js to use such information instead of always using developer-og.jpg

[mportiz08]

To clarify, I think we already have the right data to populate the meta tags needed for this—however, I think the logic will need to live in Swift-DocC since it would need to dynamically generate the right metadata in the individual HTML files that it produces as part of supporting static hosting environments.

We can update the metadata.js logic to select a more specific image, but that will still only be client-side logic that only happens after the page has already loaded. At the present, that logic does not yet impact the static HTML on the filesystem, which may be needed to fully support many systems that use the open graph data.

[Kyle-Ye]

Got the point. We should do the logic when swift-docc produce the static HTML file if possible.