Support GitHub-style themed images

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

A remark plugin to turn GitHub themed images:

![GitHub-Mark-Light](https://user-images.githubusercontent.com/3369400/139447912-e0f43f33-6d9f-45f8-be46-2df5bbc91289.png#gh-dark-mode-only)![GitHub-Mark-Dark](https://user-images.githubusercontent.com/3369400/139448065-39a229ba-4b06-434b-bc67-616e2ed80c8f.png#gh-light-mode-only)

How does it work?

GitHub just uses CSS to hide the images with a given fragment. So you can even have them separated:

Dark mode only:

Light mode only:

I guess we don't have to implement this part, just use the existing theme image component

Into the ThemedImage JSX:

<ThemedImage
  alt="GitHub Mark"
  sources={{
    light: useBaseUrl('/img/github-light.png'),
    dark: useBaseUrl('/img/github-dark.png'),
  }}
/>

Has this been requested on Canny?

No

Motivation

GitHub has added support for themed images: https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/

We have tried hard in the past to support GitHub features, it's now time for us to support this one.

API design

This will be done under the hood as part of mdx-loader and only exposed in the future as a preset option after #5999.

ThemedImage may be more natural and well-integrated with our theme approach, but we may also use plain CSS like GitHub does...?

Have you tried building it?

No response

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

Related to discussion: https://twitter.com/wooorm/status/1463877371140923398

I don't really like the gh- prefix 😅

Maybe it should be part of the remark gfm plugin?

[Josh-Cena]

I don't really like the gh- prefix 😅

Me neither, feels like it's not really extensible. But after all this doesn't have to be documented—it can just be a nice little feature for existing GitHub users.

Maybe it should be part of the remark gfm plugin?

It's either we or no-one. GitHub themselves just used CSS (Titus mentioned that as well). Both images end up in the markup, with one hidden:

So remark-gfm doesn't need to do anything special—they just need to ask users to implement the same CSS. (In fact, what can they do? Themed images can't be purely HTML anyways) I'm fine with us using CSS to hide it as well, but adding a little remark plugin would make the ThemedImage component more useful than it currently is

[Josh-Cena]

I decided that nothing should be done. This could easily be achieved with CSS in userland.

[felipecrs]

Just in case someone stumbles upon this like I did, Docusaurus now supports it:

https://docusaurus.io/docs/next/markdown-features/assets#github-style-themed-images