Integration of docsify-themeable (v5)

[jhildenbiddle]

The goal of docsify-themeable integration is to provide the docsify community with a more flexible and maintainable theme system designed around CSS custom properties. A more detailed explanation can be found in the docsify-themeable documentation, but the following summary from https://github.com/docsifyjs/docsify/issues/657#issuecomment-458341229 helps explain the advantage for docsify maintainers:

Docsify currently offers four official themes: vue, buble, dark, and pure. These themes are all more-or-less the same with the exception of a handful of basic style declarations (color, typography, margin/padding, etc). To make development easier, a CSS preprocessor (stylus) is used to compile each theme by combining a shared CSS file with a theme-specific CSS file. Makes sense.

Docsify-themeable takes a similar approach but offers a much more flexible implementation by leveraging CSS custom properties. The ... advantages for docsify maintainers: a single block of CSS used for all themes, with each theme comprised of only a flat list of named values (e.g. --sidebar-background: #ccc) instead of blocks of CSS.

I've created this issue as a means of tracking progress and facilitating discussions related to the proposed change. Consider this issue a work-in-progress and expect updates to follow.

Todo

• [ ] Integrate docsify-themeable (Github) into docsify repo
• [ ] Update docsify-generated markup to align with updated CSS
• [ ] Convert remaining docsify .styl files to .scss (#1167)
• [ ] Switch from node-sass to sass package
• [ ] Update documentation

Changes from docsify-themeable 0.x

• [ ] Drop support for legacy browsers (IE10/11 support dropped in v5)
• [ ] Update to leverage modern CSS features (e.g. grid, scoped custom properties, variable fonts, filters, etc.)
• [ ] Allow sidebar links to wrap instead of being truncated (see #1179)
• [ ] Implement light/dark theme switching based on OS preference (https://github.com/docsifyjs/docsify/pull/1182#issuecomment-642330372)
• [ ] Update .mask implementation (multiple backgrounds vs. separate .mask element) (see #1233)
• [ ] Improve print styles
• [ ] Fix --content-max-width behavior (should account for sidebar expand/collapse state)
• [ ] Add ability to left-justify content instead of center (default)
• [ ] Revisit sidebar icon implementation to allow setting color via theme property (here, here)

Questions

• What themes will ship with docsify v5?

  TBD. My preference would be to ship only an updated "light" and "dark" theme based on docsify-themeable's "Simple" and "Simple Dark" themes. This would reduce the number of themes the core team has to maintain and (hopefully) encourage the community to provide additional theme options.

[mohammedsahl]

I'd like to work on:

Convert remaining docsify .styl files to .scss (#1167)

and proably, by extension,

Switch from node-sass to sass package

However, I noticed there is a discuss label on #1167. Is it finialized that we would be using PostCSS + (Dart) SASS? It'll help me decide what to invest time into learning 😃

From my understanding, .styl files seem very similar to .scss files. And since Dart Sass is distributed as a npm sass package I wouldn't have to worry about learning Dart too, right?

[anikethsaha]

I believe in order to integrate docsify-themeable, the list should be executed in order, right @jhildenbiddle ?

@mohammedsahl you can start with the top elements of the lists, #1167 is not finalized it seems and it is not the priority as docsify-themeable will work without that as well. Once that is finalized, we can do the migration

[mohammedsahl]

If that's the case then I'll just get started with what's first on the list. Does this warrant a new issue to be created? @anikethsaha

[jhildenbiddle]

Docsify-themeable integration should wait until v4 issues/PRs have been triaged. This will allow us to identify v4 work that we want to complete for v4 that could complicate the integration. Until then, this issue is just meant as a scratchpad and a discussion area, so the todos are not in order or necessarily complete.

[trusktr]

Seems we can at least get docsify-themeable into the docsify org or repo, without it being a breaking change. Maybe this can be two issues: one for bringing it in and remaining compatible with v4, and then another for v5 breaking changes.

[jhildenbiddle]

@trusktr --

Perhaps I'm misunderstanding the above comment, but we definitely do not want to integrate docsify-themeable--or any code that isn't a critical bug fix or deemed absolutely necessary--with the intention of releasing it as a future v4 of docsify. This goes against the whole idea of stabilizing v4 so we can move on to v5.