RFC: social cards

[slorber]

Issue for idea already expressed here: #2267 (comment)

Dynamic Social Cards

You might have noticed that some people / companies have an automated way to generate social cards that adapt to the underlying content (generating an image from query string params)

I think this would cool if by default, all Docusaurus docs/blogs would generate custom social cards, if the user did not define any custom social image.

This way, all Docusaurus links pasted to a social media would have a beautiful image.

By default we could even include a discrete Docusaurus + Slash logo for growth hacking 🤪

Vercel has a nice project to do this easily: https://github.com/vercel/og-image

We could fork this project, host our own variant (can be free on Vercel), and use it for D2 website, + allow other sites to use it as well.

Curretly, Docusaurus can have a default social card, but it's static and does not adapt to the content::

Here's some examples of dynamic/automated social cards:

[slorber]

Notes, there are many ways to handle these social cards.

• We could generate the cards as a build step, using a headless chromium instance in the CIs that support it.
• We could host lambdas to generate the images remotely
• We could use saas services like Cloudinary...

Interesting blog post: https://www.swyx.io/writing/jamstack-og-images/

---

@JoelMarcey

I think this is a good idea and I would be interesting in having this implemented. As far as how to implement it, I have no strong feelings. I am generally in favor of utilizing other solutions for specific features if we believe that the cost of implementing it ourselves would be so much greater. That said, we lose a little bit of control of our destiny by doing that. I am definitely curious which way others think we should go here.

What I think about potential implementations:

Generating the images at build time

Would require some kind of headless browser in the build process. I think it's likely to complicate the build process, make it slower, less portable, and potentially exceeding free quotas of popular free CIs. I think it's not the best solution.

Seen this being done here with Gasby:
https://andrewingram.net/posts/automatic-social-cards-with-gatsby/

Using a SaaS

Some people are using a SaaS like Cloudinary to generate these cards, so they don't have to host any infrastructure.

For example:
https://www.learnwithjason.dev/blog/auto-generate-social-image/

Self hosted

We could create our own solution and host it.

Other solutions are possible, but I mean forking https://github.com/vercel/og-image as a docusaurus-images project, and hosting it on Vercel for free (or negotiate some kind of free open-source usage with them).

We would make the service flexible enough so that it works great for most of the sites, yet enabling users to self host an alternative service if our default service does not suit their needs.

---

What I think we should do:

• Create a docusaurus-images (can be a fork of vercel/og-image)
• Make it flexible enough for our need (querystring should enable to customize the social card image, enable/disable a Docusaurus stamp, show docs version...)
• Host it on Vercel, making it available by default to all without having to do anything
• Expose a configuration function that takes params of the page, and return the og image url, (which by default would use the service we host)

This way, we don't complicate the build by default, yet we enable users to craft their own social image urls. They could self-host their own fork of vercel/og-images, use external services like Cloudinary, or even add the image generation as a build step using a docusaurus postBuild plugin.

[FocalChord]

hi! me and @Drewbi will be working on this issue :)

[slorber]

Great!

@anshulrgoyal also suggested we could simply use an image processing lib like sharp to create the card at build time. That's simpler than using a headless chrome, and that's worth creating a POC to see how far we can go with this approach.

[anshulrgoyal]

I was suggesting creating some template for cards and then allowing the user to provide custom stuff like text, icons, logo, images cards and we can have templates that can read mark down and extract stuff from it like for blog we can extract image and title, author and create image from it.

[slorber]

Yes, in the end we should be able to add a meta og image tag in generated pages + an image in the build folder. We also need to think about where we plug this image file generation step, we don't have anything like that in D2 afaik. Also need to think about how to make it generic so that it can work for docs, blog, pages... what's the url of such image etc... Not so simple :)

[Drewbi]

I'd personally prefer customizing the existing og-image project as many of the features are very relevant to what we are trying to achieve and all that would be required in terms of modification would be altering the html/css that gets generated internally by the function.

In order to integrate the process locally at build time we would have to create and store an image for every page and either keep track of updates or regenerate the images on the next build. While possible, at this point I feel the API would lend itself quite nicely to the job and would allow for a light weight and easy implementation. It would also allow for users to swap out endpoints if they want like @slorber mentioned.

The customization of fields would be as easy as including or leaving out fields from the query string, eg. og-docusaurus.now.sh/main%20text?logo=""&author=""&sitetitle=""&docv="2.13.4" Any of these fields could be left out and it could be handled by the API.

Either way, if we agree on some desirable fields, I can start creating designs/mockups 🎨

[slorber]

Some random thoughts.

I think it should be integrated at the theme classic level. Other themes would be responsible for adding themselves the og image system they want (if they do).

I think the theme should allow a function to generate the og image url for each page. It would take some data we provide as parameter

const config { 
  themeConfig: {
    createOGImage: ({data,defaultImage}) => {
      if (data.type === "myCustomDocType" {
        return "https://cloudinary.com/someThing?"+serialize({title: data: title});
      }
      return defaultImage; // defaultImage would be an url to the hosted og-docusaurus hosted service 
    }
  }
}

Eventually, we could allow the user to generate himself the images at build time using an async function?

const config { 
  themeConfig: {
    createOGImage: async (data) => {
        const relativeFilePath = path.join("og_images",random()+".jpg");
        const filePath = path.join(__dirname,"build","og_images",random()+".jpg");
        await writeFile(filePathgenerateOgImageWithSharp(data));
        return "https://myDocusaurusSite/"+baseUrl + relativeFilePath;
    }
  }
}

This function couldn't be called from React directly (as the browser does not have access to nodejs apis like sharp/fs etc), so I think the blog/docs plugin should call it with the blog/doc metadata, and inject it into the theme components as props. (BlogPostPage/DocItem)

---

Not totally sure about this api, feedbacks welcome. We should probably make the system generic enough so that it can be used as well for custom pages (+ the upcoming markdown pages: #2947).

---

@Drewbi I think it's safe to say that we need at least 3 types of social cards:

• docs: title, version?...
• blog: title, author, author picture, tags...
• pages: title

I think the fields should vary according to the kind of docs, so we probably need multiple designs.

In all cases I think including the site logo is nice, and an opt-out Docusaurus logo for growth hacking 🤪

[anshulrgoyal]

@slorber I was thinking of adding it to some place like StaticSiteGenerator plugin. We can allow the user to modify options and pass a custom function that will be envoked inside ejs, with all the page meta data