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

[jhildenbiddle]

So what if we just release v5 now (with any small changes any of us think we can fit in within, say, a week or two), and it doesn't have to be super exciting, and move onto the next release?

This is more-or-less what we are planning on doing.

Things have changed since my 10/17/23 comment above. A handful of new features and fixes have been added to the develop branch that should be made available as soon as possible. Due to the refactor that occurred, we are forced to release these updates as v5.

The short-term plan is to triage the existing issues, identify those that we would like to include in v5 (if any), then release v5. We will then pivot towards v6 which (as of the time of this writing) will likely be focused on UI/UX updates and additional codebase modernization/refactoring.

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

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