Support open graph

[Fil]

Design and implement a system (template? hook? options in frontmatter?) that allows the developer to add proper tags so that their page has the relevant information to create a "card" or "summary" on social platforms. Usually:

• the title
• an og:image (typically 1200 × 630)
• a description
• the canonical url (#179)

This needs the origin and base options (#180).

[mbostock]

Same comment as https://github.com/observablehq/cli/issues/179#issuecomment-1813088427: this issue needs further specificity to be actionable.

[Fil]

This can be done with #253

[Fil]

Exposing meta data to the page could help in more scenarios. see https://github.com/observablehq/framework/issues/1036

[pettiross]

OG images would also let us show thumbnails for projects and pages on the platform.

[Fil]

related: #168

[pettiross]

+1 to using the front matter for this. We could expand on the front matter + observable.config.ts combination we have today so project-level defaults for OG metalabels could be set once and overridden on specific pages.

[mbostock]

Is this already done with the head option (and the ability to reference local assets in the head)?

[Fil]

Not quite yet. I'd like to explore a possibility for the head option (as well as header and footer) to be specified as a function, that would receive as arguments some meta data about the project config (including the origin option #180), and the current page (front matter, title, and possibly contents/files, if the user wants to insert an excerpt / summary or pick the first image from the contents) #1036. (Also mentioned https://github.com/observablehq/framework/issues/56#issuecomment-2016549988.)

EDIT: I've now explored this ~~and it's a pretty simple and straightforward change to getHtml()~~ and it's not so simple.

[mbostock]

I’m still not sure what this needs. Why not specify the head front matter option? Do we just want shorthand so you can specify a description front matter option (and maybe image) instead that gets promoted to the corresponding meta elements in the head?

[Fil]

The way I imagine this, the configuration head option, if specified as a function (#1255) would receive meta data, from the page's front matter (or first H1 if the title is not defined as front matter), and would build the og "card" from these values — it seems like a common convenience in CMS.

I did not even consider typing everything explicitly, although it (almost) works:

---
head:
  <meta property="og:title" content="Page title"/>
  <meta property="og:description" content="This is a nice page." />
  <meta property="og:image" content="heroimage.png"/>
  <meta property="og:image:width" content="1200"/>
  <meta property="og:image:height" content="630"/>
---

Unfortunately it does not work fully because og:image must be an absolute URL (per spec, even though the official website ogp.me is a bit more fuzzy on this point). But, if we make it absolute, it's not picked up by Framework as being a file attachment, and not built.

The absolute URL issue could be fixed automatically but would require the origin option (#180). If we want to make this more convenient, the title should be picked up automatically as well as the image's dimensions. (And maybe the description could be automated too.)

[Fil]

OpenGraph is only useful for public projects, and in that case it's much easier to point to the og:image in another web service than to try and create an absolute URL locally in the SSG. At least this is what I do now in pangea, pointing the image to jsdelivr, that serves the content from github. for instance, https://observablehq.observablehq.cloud/pangea/plot/voronoi-treemap now references jsdelivr...thumbnail/plot/voronoi-treemap.png.

See this debug view.

Supporting the other "card" or "og" fields (title, etc) is feasible within the same head() function. My implementation is certainly far from perfect, and people might want to iterate on this, but I thinkg we can do it in userland and don't need anything more from Framework. We could discuss it further in the blogging-like functionality discussion.

[mbostock]

Quick update on @Fil’s current techniques… (@Fil correct me if anything in this description is wrong; sharing guidance in case anyone else similarly wants thumbnails.)

Pangea currently uses Playwright to take screenshots in generate-thumbnails.ts.

This script is run manually and the thumbnails are committed to the source repo in the thumbnails folder. This is because running Playwright is expensive (slow) and we don’t want to run it every time we build the site. (Maybe in the future these thumbnails could be stored in a cache so they automatically update then the code changes… 🤷)

The head config option is specified as a head function to generate the og:title and og:image meta data elements. It also includes a link element to ensure that the generated thumbnails are included in the built site.

A og_image function computes the SHA-256 content hash of the thumbnail so that it matches Framework’s behavior. This is necessary because Framework won’t rewrite og:image and twitter:image meta data elements automatically — and even if it did, it would need to know the origin of the site in order to produce a full URL, which would require the origin config option. #180