Integration of docsify-themeable (v5)

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.

[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

[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.