docsify 5.0 roadmap

[QingWei-Li]

New Features

• New Feature: Generate static html Generate static HTML site (static site generation, SSG) #136
• New Markdown Syntax: GitHub(or GitLab) Flavored Markdown ref
• New Markdown Syntax: Friendly doc Helpers, Friendly doc Helpers #413
• New Option: For relative file paths rather than relative root, fix fix: resolve relative path #593

Breaking Changes

• Remove lib and themes folder from the repo

Deadline

December^maybe February Soon

[Ivlyth]

what about generate diagrams and flowcharts from text using Mermaid ?

[sansnom]

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

[timaschew]

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

[timaschew]

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.

[timaschew]

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: #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/)

[sansnom]

@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". :)

[timaschew]

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

[jhildenbiddle]

A few additional proposals for 5.x:

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

2. 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)

   

3. 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. 😄

[jthegedus]

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 🎉

[jhildenbiddle]

@jthegedus --

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

• http://gs.statcounter.com/
• https://www.w3counter.com/globalstats.php
• https://en.wikipedia.org/wiki/Usage_share_of_web_browsers
• https://netmarketshare.com/browser-market-share.aspx

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.