Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes RFC: social cards #2968) and the maintainers have approved on my working plan.

Motivation

Allows users to provide a function with some static options that are used to generate social card urls for the site inside docusaurus.config.js. The function is run in a Node environment, so users can access and create local files. Users can also provide a static url.

In addition, I have a social card generation service hosted here. The code is here. The preview page is a work-in-progress, but the API is fully functioning.

There were a few extra changes I had to make. Mainly shuffling around a few util functions to avoid adding dependencies when possible.

• Moved isInternalUrl to docusaurus-utils-common. It is still exported in the client API as @docusaurus/isInternalUrl
• Moved addBaseUrl to docusaurus-utils-common. It is used for useBaseUrl, but I also need it to add the base url to projectLogo when getting the social card url in Node
• Added docusaurus-utils-common as a dependency for docusaurus-utils in order to access addBaseUrl
• Added replacer function to serialize url function for docusaurus.config.js

One issue with this approach is that I don't think there is a way to use the function for JSX pages. As a workaround, in <Layout>, I added an option for users to set the socialCardUrl manually. This is a bit repetitive though. I have another implementation that works for JSX pages by passing the function to React. However, this does prevent any access to the local filesystem, limiting the flexibility of the function. What are your opinions on this implementation?

This new feature replaces the theme config image option. Should we remove that option?

Test Plan

Updated the current plugin tests with socialCardUrls.

Tested the default social card url generator function with the following:

• default value
• default value with custom projectName
• default value with custom projectName with special characters
  For each type of page (docs, blog, pages)
• title with special characters
• version with special characters
• authorName with special characters
• authorImage with special characters
• permalink doesn't affect URL (intentional, users can choose to use the permalink if they want)
• projectName with special characters
• projectLogo with special characters
• undefined baseUrl
• undefined docusaurus
• docusaurus = true
• docusaurus = false
• undefined markdown
• markdown = true
• markdown = false
• undefined theme
• theme = light
• theme = dark

Dogfooding:

• /tests/pages/social-card-service-tests has an example of setting socialCardUrl through <Layout>.

Test links

Deploy preview: https://deploy-preview-7836--docusaurus-2.netlify.app
Dogfooding page: https://deploy-preview-7836--docusaurus-2.netlify.app/tests/pages/social-card-service-tests/

There are 14 different components in theme-classic that use , which I am using to set og:image and twitter:image. Below, I have a link to each type of page, as well as a preview page for its social card.

1. NotFound
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/not-a-page
   Card: Preview sites don't work, probably because the page is not found. However, the meta tag is there.
2. BlogArchivePage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/blog/archive
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fblog%2Farchive
3. BlogListPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/blog
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fblog
4. BlogPostPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/blog/2021/03/09/releasing-docusaurus-i18n
   Card: Preview doesn't work because there is another image overriding it. However, the meta tag is on the page: https://docusaurus-og-image.vercel.app/Releasing%20Docusaurus%20i18n?authorName=S%C3%A9bastien%20Lorber&authorImage=https%3A%2F%2Fgithub.com%2Fslorber.png&projectName=Docusaurus&projectLogo=https%3A%2F%2Fdocusaurus.io%2Fimg%2Fdocusaurus.svg&markdown=true&docusaurus=true&theme=light&
5. BlogTagsListPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/blog/tags
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fblog%2Ftags
6. BlogTagsPostPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/blog/tags/adoption
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fblog%2Ftags%2Fadoption
7. DocCategoryGeneratedIndexPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/docs/category/getting-started
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fdocs%2Fcategory%2Fgetting-started
8. DocItem/Metadata
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/docs/installation
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fdocs%2Finstallation
9. DocTagDocListPage
   Page: https://deploy-preview-7836--docusaurus-2.netlify.app/tests/docs/tags/b
   Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Ftests%2Fdocs%2Ftags%2Fb
10. DocTagsListPage
    Page: https://deploy-preview-7836--docusaurus-2.netlify.app/tests/docs/tags
    Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Ftests%2Fdocs%2Ftags
11. Layout
    Page: https://deploy-preview-7836--docusaurus-2.netlify.app/tests/pages/social-card-service-tests
    Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Ftests%2Fpages%2Fsocial-card-service-tests
12. MDXPage
    Page: https://deploy-preview-7836--docusaurus-2.netlify.app/examples/markdownPageExample
    Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fexamples%2FmarkdownPageExample
13. SiteMetadata
    Page: https://deploy-preview-7836--docusaurus-2.netlify.app/
    Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2F
14. ChangelogList
    Page: https://deploy-preview-7836--docusaurus-2.netlify.app/changelog
    Card: https://www.opengraph.xyz/url/https%3A%2F%2Fdeploy-preview-7836--docusaurus-2.netlify.app%2Fchangelog

Related issues/PRs