Skip to content

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify and modernize Docsify #2104

Closed
10 of 17 tasks
trusktr opened this issue Jun 25, 2023 · 1 comment
Closed
10 of 17 tasks

Simplify and modernize Docsify #2104

trusktr opened this issue Jun 25, 2023 · 1 comment

Comments

@trusktr
Copy link
Member

trusktr commented Jun 25, 2023

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)

Future release if not v5

Non breaking changes:

Potentially Breaking changes:

  • We have both /index.html and docs/index.html. Do we need duplicate code? Delete one.
  • Update dependencies so that we can delete CommonJS from Rollup config
  • 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.
@trusktr trusktr mentioned this issue Jun 25, 2023
9 tasks
@Koooooo-7 Koooooo-7 pinned this issue Jun 29, 2023
trusktr added a commit that referenced this issue Jul 16, 2023
…private methods and properties to start to encapsulate Docsify

Also some small tweaks:

- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code
- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify

This handles a task in [Simplify and modernize Docsify](#2104), as well as works towards [Encapsulating Docsify](#2135).
trusktr added a commit that referenced this issue Jul 17, 2023
…private methods and properties to start to encapsulate Docsify

Also some small tweaks:

- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code
- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify

This handles a task in [Simplify and modernize Docsify](#2104), as well as works towards [Encapsulating Docsify](#2135).
trusktr added a commit that referenced this issue Jul 17, 2023
…private methods and properties to start to encapsulate Docsify

Also some small tweaks:

- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify
- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code

This handles a task in [Simplify and modernize Docsify](#2104), as well as works towards [Encapsulating Docsify](#2135).
This was referenced Jul 17, 2023
Koooooo-7 added a commit that referenced this issue Aug 9, 2023
* chore: add missing Vue support for Vercel builds

* refactor: move some functions and module-level state into classes as private methods and properties to start to encapsulate Docsify

Also some small tweaks:

- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify
- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code

This handles a task in [Simplify and modernize Docsify](#2104), as well as works towards [Encapsulating Docsify](#2135).

* chore: add prettier code format check to our lint script, and add a prettier script for manually formatting the whole code base

* chore: update issue/pr templates

* chore: apply our format to the whole code base


---------

Co-authored-by: Koy <[email protected]>
Co-authored-by: i544693 <[email protected]>
@jhildenbiddle
Copy link
Member

jhildenbiddle commented Oct 17, 2023

@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

@docsifyjs docsifyjs locked and limited conversation to collaborators Mar 1, 2024
@jhildenbiddle jhildenbiddle converted this issue into discussion #2376 Mar 1, 2024
@jhildenbiddle jhildenbiddle unpinned this issue Mar 1, 2024

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants