Dark Mode Theme

[pzuraq]

I think a general dark mode, similar to the Rust docs, would be awesome to add for users who prefer to read on a darker background.

Theming options in general would probably be a good idea to add too, but I'd like to see it done in an organized way so users don't end up adding tons of custom styles, and it makes writing docs easier (convention over configuration here)

[samselikoff]

100% agreed, been thinking about this because I'm going to want it for Mirage's docs sites.

I honestly think we should start with a super-constrained api, possibly string config values on a service.

Thinking maybe we unify the services under an addonDocs service that has the routes, search, project version data, etc. Users could then subclass in their own app and specify some theming options to start (which would then be easily available to the app, since the addonDocs service would be a global singleton):

// dummy/app/services/addon-docs.js
import { AddonDocs } from 'ember-cli-addon-docs';

export default AddonDocs.extend({

  theme: {
    primaryColor: '#123456'
  }

});

I like this being the simple first entry point for customizing theme. Just a thought for now, many ways we could do this.

[pzuraq]

That sounds like a solid way to approach it, and definitely agree a constrained API would be ideal

[gossi]

I recently themed our docs (our designers come up with a great design). I can tell it was a pain in the ass to do and very hacky as well (ec-addon-docs is not very theming friendly). It was more like overriding these functional css classes providing a proper path for that specific occurence. I'd wish for more generic css classes on various elements in the first place (going the classical way). In the longrun to make theming enjoyable, css classes + configuration?). Remember if something is not configurable, we will hack it in the evil way 😛

[samselikoff]

@gossi Thanks for sharing, and I do believe it was a pain. However our CSS really should be seen as private, it could change any release.

That said, if folks are doing this there's an obvious need, and I think we can come up with a better solution.

I think overwriting CSS is rough even with more structured class names. A better solution would be for us to provide renderless components that render out the navs and pages, and don't provide any opinions about structure or presentation.

Could you post some screenshots (or a link) to your docs? Also, are these internal or OSS?

[gossi]

Thanks for sharing, and I do believe it was a pain. However our CSS really should be seen as private, it could change any release.

Yes, I have fears about that one 😇

What I meant with more meaningful CSS: At the moment this is just functional CSS classes and with given the right "CSS path" you can adress the element you want. What I meant is the idea to put additional "semantic" css class names. They must not be used by ec-addon-docs but would provide a "hook" for themes to inject their styles (or do I think to old-fashioned?)

Docs are internal and were just started with the design that we got. Will try to send you a screenshot on discord along with my css file.

[samselikoff]

Haha - it's not about being old-fashioned or not. I understand semantic css class names would make it easier to override, but I think if folks are overriding in the first place then there's a problem. Overriding has never been a good public API for changing styles – I think we can do much better with renderless Ember components.

[jacojoubert]

Dark mode support in some fashion via @media (prefers-color-scheme: dark) {} would be great since my addon supports dark mode and it looks really jarring to have dark components on a white docs site.