Giters

docsifyjs / docsify

🃏 A magical documentation site generator.

Home Page:https://docsify.js.org

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

All distributable files belong in the same directory (move all to `dist/`)

sy-records opened this issue · comments

commented

We actually need it because it's referenced in the documentation. see https://docsify.js.org/#/quickstart?id=specifying-docsify-versions

Good catch, however I do not think we should restore the /themes directory.

Having duplicate files in multiple locations in a single repo is a bad idea. Doing so invites confusion among those unfamiliar with the details of why duplicate files exist, which can lead to public-facing mistakes that require long-term support. This is an excellent example, and I believe it is a mistake we should correct for v5:

  1. The next release is going to be a breaking change because our codebase no longer supports legacy browsers. If we want to make a change, this is the time to do it.
  2. Our documentation should not recommend loading unminified CSS or JS files on a production site. Similarly, our CLI output should not load unminified CSS or JS by default. We can offer unminified CSS/JS as options, but our recommendation should be to use minified CSS/JS.
  3. All distributable files belong in the same directory. For v4, this is /lib. For v5, the proposed location is /dist.
  4. If we want to offer minified and unminified CSS files, we should differentiate using the filename and not the location, just as we do with docsify.js anddocsify.min.js. For v5, this would mean something like /dist/themes/vue.css and /dist/themes/vue.min.css. #2338

I planned to address this issue in an upcoming PR as part of our v4 => v5 transition:

  1. Modify build to output distributable files to /dist instead of /lib. This is part of the v4 => v5 transition.
  2. Update URLs as needed in docsify and docsify-cli repos to reference /dist instead of /lib.
  3. Create static redirects/imports from /lib and /themes to @4/lib and @4/themes CDN URLs. This allows v4 sites without a URL version lock to continue working when they unintentionally load v5 after its release.
  4. Add a console deprecation / upgrade notice for sites loading resources from /lib or /themes redirects/imports.

The static redirects/imports in /lib and /themes are a temporary solution. They exist only to prevent sites that load docsify resources without URL version locks from breaking when v5 releases because v4 was released in 2017 but our docs did not recommend URL version locks until mid-2020. My hope is that they will can remove them by the time v6 is released.

Originally posted by @jhildenbiddle in #2335 (review)

commented

Updated the title to reflect moving stuff into dist/