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 browser (Firefox with 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:

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