OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard
verified publisher icon OAI

Add dark mode support to the HTML versions of the OpenAPI specs

Open mikekistler opened this issue 1 year ago • 5 comments

Update the rendering process for the HTML versions of the OpenAPI specs (using ReSpec) to generate pages that support dark mode.

ReSpec has added dark mode support: https://github.com/speced/respec/issues/2651

Related: #3576

mikekistler avatar May 30 '24 16:05 mikekistler

Paging @Bellangelo (we're working on making it so that we can assign issues to you, but haven't quite sorted that out yet).

handrews avatar May 30 '24 18:05 handrews

Unfortunately, this seems not to be so easy. Our js/respec-oai.js file loads this css file https://www.w3.org/StyleSheets/TR/2016/base.css which overrides most styles. There is a https://www.w3.org.org/StyleSheets/TR/2026/dark.css but even if we add it, it still gets overridden by the base.css. It looks like we need to give more effort in this issue https://github.com/OAI/OpenAPI-Specification/issues/3845 which will help us have more control over the respec-oai.js

Bellangelo avatar Jun 02 '24 19:06 Bellangelo

ReSpec documentation of dark mode says

Note: This is supported for W3C specs only, and makes use of official dark.css in tr-design.

We can enable the switch, and it has no effect 😞

image

ralfhandl avatar Jul 08 '24 14:07 ralfhandl

@mikekistler Don't know what changed in the last two weeks, now dark mode seems to work (at least if your system theme is set to dark mode):

  • https://ralfhandl.github.io/OpenAPI-Specification/oas/latest-dark.html

Quite some fine-tuning needed for dark mode to really work:

  • different OAS logos for light/dark mode
  • table and code-block background color depending on light/dark mode
  • ...

I'll gladly leave this to someone fluent in CSS 😁

ralfhandl avatar Jul 25 '24 21:07 ralfhandl

I have started on this, please assign to my name.

Intermediate results can be seen here: https://pavelkornev.github.io/OpenAPI-Specification/oas/latest.html

pavelkornev avatar Sep 03 '24 20:09 pavelkornev

Hi @pavelkornev, I used some of your CSS in this PR to continue on this work. If you have already a PR that I missed then I can close mine and use yours instead.

Bellangelo avatar Dec 19 '24 07:12 Bellangelo

Hi @pavelkornev, I used some of your CSS in this PR to continue on this work. If you have already a PR that I missed then I can close mine and use yours instead.

The approach i tried won't work because then switcher between Dark/Light mode doesn't work properly. Try both scenarious:

  1. System settings set to Light mode: try switch between Dark/Light using switcher
  2. System settings set to Dark mode: try switch between Dark/Light using switcher

pavelkornev avatar Dec 19 '24 08:12 pavelkornev

Hi @pavelkornev, I used some of your CSS in this PR to continue on this work. If you have already a PR that I missed then I can close mine and use yours instead.

The approach i tried won't work because then switcher between Dark/Light mode doesn't work properly. Try both scenarious:

  1. System settings set to Light mode: try switch between Dark/Light using switcher
  2. System settings set to Dark mode: try switch between Dark/Light using switcher

Thanks a lot @pavelkornev for your feedback ❤ . I had encapsulated the styling under the preferred-color-scheme. It should be fixed now. See https://github.com/OAI/OpenAPI-Specification/pull/4268/commits/973999a6a7c1e774b72ca44aa24cf53d4647f782

Bellangelo avatar Dec 19 '24 11:12 Bellangelo