Simplify and modernize Docsify

[trusktr]

We have some baggage,

• support for CommonJS build from ES Modules, and code that is CommonJS
• old code to support ancient browsers like IE 11, which is dead
• experimental and incomplete SSR that no one has had been interested in or had time for finishing, and some of us believe there is a better way forward
• old .styl syntax for our CSS. CSS has lots of new language features, including CSS Nesting which is out in all browsers (Firefox with a flag now in Firefox without a flag), container queries, etc.

I propose:

v5

(Any chained pull requests are in the same order as in this list)

• delete SSR #2105
• Get rid of CommonJS module format, use only ES Modules. #2102
  • Delete example tests. We have Jest and Playwright documentation for that.
• Update Rollup, remove Buble, we'll write reasonably modern code (other people with old browser requirements can easily rollup/webpack their own Docsify, but IE is completely dead). chore: update rollup #2109
• Modernize source code (besides module format):
  • In a first PR, remove polyfills, use newer language features, drop support for IE (IE is dead!). pull request #2114
  • In a second PR refactor some "private" function-based class methods to not use .call, but rather be private methods. refactor: move some functions and module-level state into classes as private methods and properties to start to encapsulate Docsify #2136
    • This is in a separate PR because it will move code around, while the first PR will only have inline replacements like var -> const, or for(;;) -> for(of), so it will be easier to review them sepately
• Ensure all code is auto-formatted. Ensure code format #2138

Future release if not v5

Non breaking changes:

• Add type definitions. chore: output type definitions #2392
• Bring docsify-cli into this repo for easier development. #2277
• Update from deprecated ESLint v8 config format to the new v9 "flat config" format that now supports ES Modules.
  • We can't convert until our plugins support the new format.
    • [Feature Request] Support new ESLint flat config import-js/eslint-plugin-import#2556
    • Compatibility with new eslint config spec (flat config) prettier/eslint-config-prettier#231
  • For now, we use .eslintrc.cjs, which is still in CommonJS format.
  • See the following for migration:
    • https://eslint.org/docs/latest/use/configure/configuration-files-new
    • https://eslint.org/blog/2022/08/new-config-system-part-2/

Potentially Breaking changes:

• We have both /index.html and docs/index.html. Do we need duplicate code? Delete one.
  • Chore: Clean up server implementation and update test docs #2316
• Remove the global API (initGlobalAPI() along with the automatic new Docsify and instead require users to pass options into new Docsify(options))
• Update dependencies so that we can delete CommonJS from Rollup config
  • Update to Prism v2.
    • Simplified ESM build PrismJS/prism#3704
  • [Dependency Notification] Upgrade marked which may gonna drop support IE11. #1885
• Delete Stylus, write vanilla CSS (using postcss for now only until CSS Nesting lands in Firefox Firefox supports nesting now). These changes should be backwards compatible for docsify-themeable. Someone with a build system might consume these files, so major version bump.
• Convert DOM creation/manipulation parts to Solid.js. We'll replace the first attempt at convert DOM creation/manipuation code to concise Solid JSX #1716 with a new one. Someone with a build might need an update, so major bump. Most people will be unaffected.
  • Solid has several features including reactivity primitives, a component system, and DOM templating. For this task, we will use Solid's component system and templating to encapsulate the DOM parts of Docsify, and output the DOM in a nicer way that will set us up for a better SSR and SSG future.
  • f.e.

    const div = <div>Some <span>{content}</span></div> // returns an HTMLDivElement.

• Possibly convert to TypeScript? Have the best intellisense and self-documented code! (Eventually I need to convert to a strict type-safe subset of TypeScript to compile it to WebAssembly). Someone building source may break, so major bump.

[jhildenbiddle]

@trusktr --

This is a good list. Thanks for putting it together and tackling much of the work.

I think it's important to recognize that while this type of cleanup work will benefit maintainers, the end result of the items listed above do not provide a compelling reason for existing users to upgrade from v4. This isn't meant as a negative comment. I think Docsify needs this work to be done and that it will be in a much better place when this work is completed. My intention is only to point out that if we are going to introduce changes that will require a major version bump, we should also consider changes that directly benefit users so that they are incentivized to upgrade.

One suggestion is update the UI visuals, HTML, and CSS for v5. If proposals for v5 include converting all of our CSS from Stylus to vanilla CSS and converting our HTML from string/templates to UI components then this would be an opportune time to do it. By incorporating lessons learned from docsify-themeable and popular component libraries we can offer an updated UI with flexible theming options. Since this change would be highly visible, I believe this change alone would motivate users to upgrade.

A few quick thoughts regarding other items on the list above:

1. I think we should consider adding Babel to our Rollup configuration along with a browserslist configuration that specifies that last "X" version of evergreen browsers ("X" is TBD, perhaps 3?). This ensures our distributables work as expected on multiple versions of evergreen browsers, which is important considering that our test environment tests only against the latest versions of the major browser engines (Blink, Gecko, and WebKit). We can still write modern JS with the expectation that Babel will transpile very little (if any) code during the build process, but Babel is there as a safeguard in case a dev uses a new JS feature that would otherwise break in an evergreen browser 1 or 2 versions behind the latest version.

2. Regarding the two index.html files, I agree this is confusing and unnecessary. This has been in place for a long time, and from what I can tell the main difference is that /index.html loads docsify-related scripts from the /lib/ folder while /docs/index.html loads those scripts from a CDN (there are other differences, but this is the major one). In my own projects I've used browser-sync as a local web server which allows me to rewrite CDN URLs to local URLs during development. The end result is the /docs/ directory loads local JS/CSS as needed during development, but CDN JS/CSS when served to the public.

3. Moving to a component-based framework for rendering and updating our UI elements makes sense and is something I'm looking forward to. I think it is important that we discuss our framework options before assuming SolidJS is the path forward. As I've mentioned previously, I have nothing against SolidJS and no strong preference for other frameworks, but all frameworks have their pros and cons and I'd like to see us make an informed decision. My vote would be to open this as an issue or discussion, see where it goes, then determine if/when/how to proceed. If SolidJS is the right choice, I'm all for it. If we determine a better option exists, we'll all be happy we had the discussion before committing to SolidJS.

Ping: @sy-records, @Koooooo-7

[sy-records]

Moving to v6 immediately after releasing v5?
Will the v5 version continue to be maintained?

[Koooooo-7]

I think whether we could release v5 now or further we need have a agreement first.
As we talked in team (discord) few days ago. I agree with @jhildenbiddle , we need clear those remain issues/pr's before we do the v5 release. I did some of them but still left some need to discuss and label them.
So, I think we need make those 2 things finish and then, we have more clear roadmap to do the v5 release and do the next.

• Add labels/categories for what we need do on v5, v5+ and next v6.
• Have a final decision and discuss cross all the remain questions and plan on the v5 and v5+.
• Collect common thoughts and focus parts in teams to make us have a clear direction where we are going.

[Koooooo-7]

Yea, I agree with you mentioned @trusktr . we could do a general release based on version x.y.z rules --- If we have some remarkable breaking changes, we do the X release, otherwise, the Y or Z. then move on.
IMO, There are leaving some tasks/management （category things and make it more clear） need to be clarify and a final discuss.
I believe it will make the next milestone more practicable and closer.
Ideally, it already have done if we all realized it and agree it with @jhildenbiddle.

If not, I think we need finish it asap and do the rest of things.

[jhildenbiddle]

Moving to v6 immediately after releasing v5?

Yes, but this is just a proposal based on the idea that the work we'll focus on immediately after the release of v5 will likely include breaking changes and therefore require a major version bump. That idea came from my proposal to focus on docsify's UI and plugin system after v5 is released, but this is admittedly TBD.

The in-progress triage of existing issues and PRs should help inform what comes after the release of v5. If we release v5 and determine we have non-breaking updates we want to focus on, then we'll focus on v5 minor and patch updates. If we choose to prioritize breaking changes, then yes, v6 is what we would focus on. If we want to focus on both, we can do that by isolating breaking changes on a separate branch and keeping that branch up to date with non-breaking changes as they are merged into the develop branch. We can cross that bridge when we get there.

The macro point is that we want to release v5 sooner than later, then turn the corner to whatever comes next.

Will the v5 version continue to be maintained?

This is also TBD, but my preference would be for us to focus on the current and next versions only, limiting work on previous versions to critical bug fixes only as needed.

[trusktr]

Will the v5 version continue to be maintained?

. we could do a general release based on version x.y.z rules --- If we have some remarkable breaking changes, we do the X release, otherwise, the Y or Z. then move on.

The macro point is that we want to release v5 sooner than later, then turn the corner to whatever comes next.

Yep, we don't have time, energy, resources to realistically want to maintain multiple versions (f.e. like Vue 2 and Vue 3). If someone needs continuous previous version support, please notify us and start a $1000 sponsorship plan (more or less depending on needs, let us know) here:

https://github.com/sponsors/docsifyjs

What we can afford right now is progressively enhancing Docsify over time, which might include breaks along the way, we'll make sure to clearly document the migration path, and we'll bump X/Y/Z accordingly. I mentioned it before, but Three.js's migration guide is a good example:

https://github.com/mrdoob/three.js/wiki/Migration-Guide

Almost every version of Three.js has a breaking change (which has not hindered it from being the most widely adopted 3D rendering library for web). The lib is big, so stable parts are very likely not to break, but parts of it that are stabilizing and progressing (especially new features, which often start in the examples folder instead of src folder) can break. For example, new THREE.BoxGeometry(1, 1, 1) is never going to break (there'd need to be a super super good reason which is very unlikely).

[trusktr]

I added a new one to the list above:

• Remove the global API (initGlobalAPI() along with the automatic new Docsify and instead require users to pass options into new Docsify)

[trusktr]

Added a new bullet to the list above:

• Add type definitions. chore: output type definitions #2392

[trusktr]

I fantasize about removing the build. For example, we could just have a src/ folder and ship ES Modules and plain CSS, and let other people optimize/build their sites as they wish (or contribute optimization (and keep maintaining it otherwise it is left onto us), or sponsor us to add optimization).

The less we have to maintain for a working product, the more we can advance features, and we can let others help us with code or sponsorship.

---

Regarding the Vue stuff, I would really like to make that a standalone plugin rather than core feature.