Swap images based on brightness

[pingbird]

It would be nice if we could use different images for dark mode than light mode. Flutter has a lot of diagrams that are incompatible with a dark theme or have a jarring white background built in.

Related: flutter/assets-for-api-docs#198

[srawlins]

I don't see us adding any sort of multi-image theme-swapping syntax any time soon. Is there CSS we can apply in dark-mode? For transparent images, maybe a bg color?

[pingbird]

What would be a good syntax?

For backwards compatibility I was thinking adding a directive after the regular markdown image syntax:

![The MaterialApp displays a Scaffold](https://flutter.github.io/assets-for-api-docs/assets/material/basic_material_app.png){@dark basic_material_app_dark.png}

[srawlins]

Whoa it looks like GitHub supports this already and I totally missed it: https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/

Here's their example:

![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)

I think we will follow this standard. I think the markdown package will not be changed at all... Instead we change the CSS in Dartdoc? And/or Flutter's CSS. Unless we cannot use a CSS selector to find #gh-dark-mode-only and #gh-light-mode-only... In that case we'll have to use JavaScript in Dartdoc's (and pub.dev's) pages.

[pingbird]

.dark-theme img[src$="#gh-light-mode-only"] {
  display: none;
}
.light-theme img[src$="#gh-dark-mode-only"] {
  display: none;
}

Should do the trick