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. #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.

[Jeehut]

For reference, I've just run into this issue as well with the WWDC Notes project. I've migrated the old site to DocC this year, but when I post session notes on social media (Twitter, Mastodon, etc.) there's no preview like it used to have on the old website. That's a bummer and if there's anything I can do to help get this done, let me know.

See for example this tweet linking to this note. Note that I've decided to take screenshots of the site and attach that as there are no cards showing, which is annoying because I can't automate that. I'd like to post these tweets automatically when new notes have been added with a rich preview, if possible.

Thank you for your consideration and hard work! DocC is awesome. 💪

[mportiz08]

@franklinsch I transferred this issue from the swift-docc-render repo to the swift-docc one, because this enhancement would have to be implemented in swift-docc itself.

Swift-DocC-Render already dynamically updates this open graph metadata on the client-side, but it is more optimal for this metadata to be built into the HTML file at the server side or where the HTML is generated for pre-built content—which is the Swift-DocC compiler in this instance.

Specifically, we would need to update the code that copies the dist/index-template.html for static hosting purposes so that it also embeds HTML <meta> tags that are unique to the individual pages (like including a title or the abstract as a description, etc). Examples can be found by inspecting the html of a loaded page in the browser—and to test that it working as expected once implemented at the DocC level, we can CURL the same page to verify that the tags are included in the HTML itself before the client-side rendering of DocC-Render takes over.

[Kyle-Ye]

I transferred this issue from the swift-docc-render repo to the swift-docc one, because this enhancement would have to be implemented in swift-docc itself.

Actually, I have created 2 issues at the beginning(One at swift-docc-render, one at swift-docc See context: #964 (comment)).

Since you transferred the issue from swift-docc-render to swift-docc, I just closed the original issue on the repo due to a duplicate.

[mportiz08]

Ah, whoops—my mistake. Thanks for clearing that up @Kyle-Ye