docsify 5.0 roadmap #657

Closed QingWei-Li closed 7 months ago

New Features

[x] New Feature: Generate static html #136
[ ] New Markdown Syntax: GitHub(or GitLab) Flavored Markdown ref
[x] New Markdown Syntax: Friendly doc Helpers, #413
[ ] New Option: For relative file paths rather than relative root, fix #593

Breaking Changes

[x] Remove lib and themes folder from the repo

Deadline

~~December^maybe~~ ~~February~~ Soon

what about generate diagrams and flowcharts from text using Mermaid ?

@MythRen there is a paragrah about mermaid support: https://docsify.js.org/#/markdown?id=supports-mermaid

My 2 cents:

generating static HTML files is a important topic, because most link checkers won't work without static HTML
global variables are very useful. Currently I don't see any way of defining global variables, across multiple mages and to use them in markdown files

I think it makes sense to add some test and fix some bugs which already lead to breaking changes by affecting the HTML output. Tests should be too hard since we can just have md as input and expect some HTMl as output. Is it correct that currently there are no automatic tests at all?

Another suggestion for 5.0 is to merge some features of doczify to the docsify CLI.

BTW: I've just pushed it, but I've already written the code a week ago.

I have another proposal which is not affecting the features itself, it's more the deployment.

Currently the lib directory is part of the master branch. Committing generated files into the source repository is actually an anti pattern. IMHO we should delete the lib directory from the repo and generate these files only to publish them to npm. This makes the whole process less error-prone. This for instance would not happen again: https://github.com/docsifyjs/docsify/issues/717 The issue is about a breaking change, but if you look to the diff of source files between version 4.8.2 and 4.8.3 you don't see any relevant changes. It seems that the srouce (package.json) was not in sync with the generated files (files in lib/)

@timaschew it's already in their plan if you check the "Breaking changes" part inside the first post: "Remove lib and themes folder from the repo". :)

@sansnom true... 🙈thanks

@QingWei-Li How exactly you want to support GFM (Github/GitLab)? GitLab is using kramdown which is written in ruby. I saw some modules on npm but they seem to be a bit outdated. There is another markdown parser which is also maintained. But I'm not sure if it's better than marked.

A few additional proposals for 5.x:

Triage existing issues first

I love the new shiny as much as the next guy, but triaging the existing issues before releasing the next major version would make life better for end-users and docsify devs.
- Mark existing issues as bugs, questions, "won't fix", etc.
- Close issues that can be closed to reduce the noise and let others know the project is actively maintained.
- Add bugs, enhancements, etc. to the backlog
- Prioritize/assign bugs/enhancements that need to be addressed for 4.x (pre 5.x release)
- Identify/assign bugs/enhancements that should be included in the upcoming 5.x release
I have a handful of issues I filed long ago that I'd love to see addressed. Even if the end result of this effort is simply closing a bunch of old issues, it is worth cleaning house before releasing a significant update that will surely generate its own share of new issues.
Reevaluate official support for IE10/11

The latest version of docsify works in both IE10 and IE11, but the docsify site along with many of the official plugins do not (see screenshots below). If IE compatibility is important, then these issues should be addressed, compatibility requirements should be made more prominent for plugin/theme authors, and some form of testing should be required before third-party plugins/themes can be listed on official documentation. My hunch is that IE10 can be dropped but IE11 support should remain, but I could easily be convinced otherwise.

docsify.js.org (IE10/11)
Consider adopting a theme system similar to docsify-themeable

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 end-user pitch is available on the introduction page, but the approach also provides 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. Legacy support is also available courtesy of css-vars-ponyfill (which I created specifically for docsify-themeable).

As a proof of concept, I would be happy to show how easy it is to make docsify-themeable's default theme look like any of the default docsify themes (vue, buble, dark, and pure) simply be specifying CSS custom properties.

Happy to help with the effort. It's good to see docsify getting some attention. 😄

Given Microsoft has all but given up on IE and even their own rendering engine in Edge, I think Docsify should ditch IE support. Firefox & Chromium browsers remain the only browsers actually used.

Getting docsify themeable into the core would be awesome :tada:

@jthegedus --

Surprisingly, IE still holds a substantial market share. It's typically ranked the second or third most popular desktop browser globally.

Dropping IE support will almost certainly affect an appreciable number of docsify site visitors, but continuing to do so comes at a cost. Is it worth it? I dunno. That's why I posed the question as something to consider for the next major release, especially given the current issues with IE.

My $0.02 is that docsify should continue to support IE in 5.x, but only if the current IE bugs are fixed and the team can prioritize compatibility moving forward. If not, then it's better to drop support and remove "Compatible with IE10+" from docsify's list of features. Another option is to fix the existing IE issues, drop official support in 5.x, and direct users who are concerned with IE compatibility to load v4 instead of v5.

This is surprising! I was under the impression since Win8 had mainstream support dropped by MS that few would still be using it. Fewer still in our industry. You have proposed a number of reasonable solutions, personally I would favour

Another option is to fix the existing IE issues, drop official support in 5.x, and direct users who are concerned with IE compatibility to load v4 instead of v5.

over the others as I do not think it's a cost a project currently looking for maintainers needs to support, especially not with v4 existing and already being mostly compatible.

Triage existing issues first

Very good idea, I had actually the same. I would also like to adapt the template for creating issues. There are some issues which are not written in english. I would like to add this as a requirement and mark all non english issues with a label and ask the people to translate it. And for these issues and every other issues which require additional context to understand we close them after 30 days (or so) of inactivity.

I've removed some label which were not used and created a new one wait for information. There are now 2 milestones: 5.0 and 4.x

Reevaluate official support for IE10/11

It's typically ranked the second or third most popular desktop browser globally.

Let's focus on http://gs.statcounter.com/ which is also used on https://caniuse.com/usage-table According to them it's ranked very low at 2.21% like Opera Mini: 2.02%

I vote to drop support for IE (I guess Edge is not affected) and also remove it from the list of features.

Consider adopting a theme system similar to docsify-themeable

Sounds great!

I don't want to start discouraging non-english speakers to contribute, although I did find it difficult to find the reasoning/discussion on this particular issue ( #720 ) as it hadn't been raised in English prior to this. I used Google translate (built into Chrome) to translate the page and read it, and it was extremely legible. My suggestion here is that we request in the Issue template that users who don't know English well, write in their own language and use Google Translate more heavily (maybe not an option in China though... I dunno)

I agree with @jhildenbiddle. Would be interesting to clarify about IE support. Ideally for me, it would be nice if the project could keep the support of IE 11 on 5.x (some users are locked on it...). If it cost too much then drop the support and if possible fix the issues in 4.x and/or write down incompatible plug-in.

@timaschew about GFM, marked (used by docsify) seems to already support it: https://marked.js.org/#/USING_ADVANCED.md It's not working for you ?

I brought this up because @QingWei-Li is mentioning this:

New Markdown Syntax: GitHub(or GitLab) Flavored Markdown ref

And I would just like to understand what exactly he mean with that. Since marked is not supporting GitLab flavoured version does it mean he wants to replace it? Or keep marked but with other options since it's already supporting GitHub flavoured version. Which features is he missing currently?

@timaschew I will only be compatible with the features common to github and gitlab.

SHA references
Issue references within a repository
Username @mentions

docsify-themeable is great, I will re-evaluate the theme features and may be merged in version 6.0. @jhildenbiddle

I have long wanted to give up IE. Maybe we can provide a polyfill for IE if necessary.

Official statement from Microsoft regarding IE10:

Beginning January 12, 2016, only the most current version of Internet Explorer available for a supported operating system will receive technical supports and security updates. Internet Explorer 11 is the last version of Internet Explorer, and will continue to receive security updates, compatibility fixes, and technical support on Windows 7, Windows 8.1, and Windows 10.

Seems like a good justification for dropping IE10 support. If we need another reason, consider the fact that docsify plugins don't work in IE10 (#514).

IE11 is another story. If we stick with stats from gs.statcounter.com per @timaschew's suggestion, IE still holds 5.73% desktop marketshare in January 2019 (mobile, tablet, and console browsers excluded). That's more than Safari or Edge, and I don't think anyone would propose we drop support for either of those browsers.

The good news is that docsify actually works fine in IE11. Docsify plugins are the issue. For example, the docsify website is broken (#515) because it uses docsify-plugin-codefund which has been written using ES6 syntax that has not been transpiled to ES5 for legacy browsers. This has been a common issue with plugins that led me to create PRs for medium-zoom, docsify-copy-code, and docsify-pagination to get them working with IE. So far these have all been easy fixes--most devs simply weren't aware that they needed to support IE or that their code would break IE.

Here's my vote for IE support moving forward:

Drop IE10 support now (since it doesn't work anyway)
Fix IE11 issues in 4.x (before 5.x release)
Continue IE11 support for 5.x (since breaking changes are not planned)
Assume IE11 support will be dropped for 6.x or the first major update with IE-breaking changes

To help support the effort:

Add browser requirements to the plugin docs
Create a boilerplate plugin repo that incorporate best practices
Make docsify's plugin system more resilient by incorporating try{} catch{} blocks around calls
Require plugins to be tested in IE before listing them in official docs
Test all plugins listed in official docs for IE11 issues and reach out to authors as needed.

Apologies for the lengthy comment. Just wanted to get this out there and hopefully move this discussion closer to a decision. I'm happy to create a separate issue to discuss further and reduce the noise in this thread of preferred.

I've been considering making some plugin templates that have standard build and compilation setups for ES+ and TS. If others are open to it, we can add them to the official repo making and point people to them. It would reduce the burden of newcomers and our need to validate them so thoroughly and manually.

On Thu., 31 Jan. 2019, 18:37 John Hildenbiddle <notifications@github.com wrote:

Official statement from Microsoft regarding IE10 https://www.microsoft.com/en-us/windowsforbusiness/end-of-ie-support:

Beginning January 12, 2016, only the most current version of Internet Explorer available for a supported operating system will receive technical supports and security updates. Internet Explorer 11 is the last version of Internet Explorer, and will continue to receive security updates, compatibility fixes, and technical support on Windows 7, Windows 8.1, and Windows 10.

Seems like a good justification for dropping IE10 support. If we need another reason, consider the fact that docsify plugins don't work in IE10 (

514 https://github.com/docsifyjs/docsify/issues/514).

IE11 is another story. If we stick with stats from gs.statcounter.com http://gs.statcounter.com/browser-market-share/desktop/worldwide/#monthly-201901-201901-bar per @timaschew https://github.com/timaschew's suggestion, IE still holds 5.73% desktop marketshare in January 2019 (mobile, tablet, and console browsers excluded). That's more than Safari or Edge, and I don't think anyone would propose we drop support for either of those browsers.

The good news is that docsify actually works fine in IE11. Docsify plugins are the issue. For example, the docsify website is broken (#515 https://github.com/docsifyjs/docsify/issues/515) because it uses docsify-plugin-codefund https://github.com/njleonzhang/docsify-plugin-codefund which has been written using ES6 syntax that has not been transpiled to ES5 for legacy browsers. This has been a common issue with plugins that led me to create PRs for medium-zoom https://github.com/francoischalifour/medium-zoom, docsify-copy-code https://github.com/jperasmus/docsify-copy-code, and docsify-pagination https://github.com/imyelo/docsify-pagination to get them working with IE. So far these have all been easy fixes--most devs simply weren't aware that they needed to support IE or that their code would break IE.

Here's my vote for IE support moving forward:

Drop IE10 support now (since it doesn't work anyway)

Fix IE11 issues in 4.x (before 5.x release)

Continue IE11 support for 5.x (since breaking changes are not planned)

Assume IE11 support will be dropped for 6.x

To help support the effort:

Adding browser requirements to the plugin docs

Create a boilerplate plugin repo that incorporate best practices

Make docsify's plugin system more resilient by incorporating try{} catch{} blocks around calls

Require plugins to be tested in IE before listing them in official docs

Test all plugins listed in official docs for IE11 issues and reach out to authors as needed.

Apologies for the lengthy comment. Just wanted to get this out there and hopefully move this discussion closer to a decision. I'm happy to create a separate issue to discuss further and reduce the noise in this thread of preferred.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/docsifyjs/docsify/issues/657#issuecomment-459245966, or mute the thread https://github.com/notifications/unsubscribe-auth/AT1cLgsJwtxUjBEuGQGVMf0feQw27yTTks5vIp0pgaJpZM4X9tWT .

So is everybody fine with dropping IE 10 and support only IE 11?

It seems like this may be a good time to discuss #386 as well.

@timaschew mentioned the need for adding tests to docsify which I whole-heartedly agree with. Writing tests isn't the most exciting work for most devs, and without a framework in place there is very little motivation to do so. Agreeing on a testing framework and implementing tests for even a small percentage of the codebase would go a long way towards setting the standard moving forward.

All four of the new features proposed for 5.0 are good candidates for automated testing. We could limit the initial set of tests to these features only to improve the reliability of the 5.x launch and reduce the delay imposed by adding a testing framework. Presumably these new features will need some kind of testing anyway, so the impact on the release could be negligible.

Like the other issues, happy to create a new PR for further discussion if needed.

Let's start with unit testing or whatever we call it what I've already setup in this PR: #760

Hamburger menu

It hides menu entries of the sidebar (if that has many entries) on larger screens and overlaps the full length of the left side of the main area on smaller screens.

Search

Results are shown in sidebar (1) as source code (2)
- Maybe show results in the main area with highlights in rendered view
Neither works on single page docs nor across translations, which it both used to. Not sure if this is a regression. Compare jhildenbiddle/docsify-themeable#18

Readability & Navigation

Maybe it would make sense to sometimes more closely match layout and behaviour of vuepress?

or slightly larger fonts
for improved search accessibility
dynamically change URL when scrolling and navigating the page to keep a history in user's browser of their path of navigating through the page(s)
add edit links, last edited info and pagination links to core

PWA functionality

add as default to core?

dynamic theme

compare https://www.macstories.net/news/safari-technology-preview-allows-websites-to-switch-themes-based-on-mojaves-dark-mode/

Not sure if there's a way to detect it on Windows.

@jrappen --

Some good ideas in there, but it's unlikely that they will be managed well when added as a bundle of issues to an existing issue. Creating separate issues will allow each one to be tracked and triaged for upcoming releases much more easily.

I could do that.

Why is the removal of the lib and themes directory from the GitHub repo considered a breaking change? Neither the npm package nor the CDN URLs (which are based on the npm package contents) will be affected, so these changes shouldn't require a major version bump.

All other proposed changes are additions, so it seems like a minor version bump should suffice.

Also, I recommend adding #780 to the target list for 5.x. It's a small amount of work that can prevent a lot of headaches when the next major version is released.

New Markdown Syntax: GitHub(or GitLab) Flavored Markdown ref

Docsify needs a new markdown parser.

I think github uses the c++ version of this https://github.com/benmills/robotskirt

I'm pretty sure you won't be able to use it out of the box in the browser because of its native bindings. What's about https://markdown-it.github.io/ ? I have good experience with it.

Yes I am considering markdownit only https://github.com/docsifyjs/docsify/issues/823#issuecomment-557700008

Although it would have been better to get the GitHub parser to work in js as it would render consistently in docsify.

Closing this in favor of https://github.com/docsifyjs/docsify/issues/1061 (which links to each feature as a separate issue) so that we only have one issue for this. If you have any ideas, please meet us there. :)

Also see the 5.0! project board for progress.

@anikethsaha Maybe some things from here need to be moved over there?

What I'll do is re-open this, put it in the In progress column, so that we can go through it and move over anything we might need to the other issue.

dynamic theme

compare https://www.macstories.net/news/safari-technology-preview-allows-websites-to-switch-themes-based-on-mojaves-dark-mode/

Not sure if there's a way to detect it on Windows.

Yes we can do it, already my plugin docsify-darklight-theme enabled this feature for docsify sites.

@boopathikumar018

dynamic theme

compare https://www.macstories.net/news/safari-technology-preview-allows-websites-to-switch-themes-based-on-mojaves-dark-mode/

Not sure if there's a way to detect it on Windows.

Yes we can do it, already my plugin docsify-darklight-theme enabled this feature for docsify sites.

With V4 and Themeable, you can already load dark or light themes without any plugin based on the OS preferences.

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
<link rel="stylesheet" media="screen and (prefers-color-scheme: dark)" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">

Same for syntax highlighting

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/prism-theme-night-owl@1.4.0/build/light.css">
<link rel="stylesheet" media="screen and (prefers-color-scheme: dark)" href="//cdn.jsdelivr.net/npm/prism-theme-night-owl@1.4.0/build/style.css">

This behavior is really simple now and devs can handle it in many ways, without any opinionated plugin limitation. As a docsify user and CSS developer, I would never use an integrated plugin. The only missing feature about this topic, is a three-state switcher which let user to use a light, dark or automatic theme (auto should rely on the OS preferences)

@jhildenbiddle

IE11 is another story. If we stick with stats from gs.statcounter.com per @timaschew's suggestion, IE still holds 5.73% desktop marketshare in January 2019 (mobile, tablet, and console browsers excluded). That's more than Safari or Edge, and I don't think anyone would propose we drop support for either of those browsers.

The stats you're mentioning are about all the IE versions. In fact, IE 11 only have 2.29%: https://gs.statcounter.com/browser-version-market-share#monthly-201901-201901-bar

How about dropping IE support altogether?

When counting all browsers (incl. mobile), IE11 usage is now below 0.65%.

StatCounter-browser_version_partially_combined-ww-yearly-2021-2021-bar
^{Source: https://gs.statcounter.com/browser-version-partially-combined-market-share#yearly-2021-2021-bar}

Even if mobile browsers are excluded, IE11's market share is still below 2% worldwide.^src

Popular frameworks and libraries are dropping IE11 support as well including Bootstrap, Angular, and Vue.js.

I assume the remaining users are mainly companies. However, major business software vendors are abandoning IE11 this year:

Microsoft services are dropping the IE support. (Source)
SAP also discontinues IE11 support for their products. (https://github.com/SAP/openui5/issues/1697#issuecomment-705206793)
Oracle has already stopped caring about IE11 users since July 2020. (Source)

Today, with the new MS Edge (Chromium), IE-only websites can be added to the Enterprise Mode Site List (Watch intro and guide) which Edge then renders in the IE-mode within the same single browser. At the same time, Edge is now also available for all supported Windows versions (7, 8.1, 10, Server, etc.) unlike the classic Edge.

I see no reason to support IE11 in 2021.

Update: today (May 19, 2021), Microsoft officially announced the EOL of the IE11 support.

The Internet Explorer 11 desktop application will be retired on June 15, 2022.

docsifyjs / docsify