chore: Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5. (#2667)

* Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5.

- add a script to build the legacy v4 lib/ and themes/ folders
- append deprecation console warnings to the v4 JS files during the v4 build
- add a script to clean v4 build outputs
- hook the v4 build/clean scripts into the release.sh script
- test the v4 build and clean in CI

* fix: update repository field format in package.json

---------

Co-authored-by: Luffy <52o@qq52o.cn>

Author: trusktr

.github/workflows/test.yml

@@ -72,6 +72,25 @@ jobs:
         run: npx playwright install --with-deps
       - name: E2E Tests (Playwright)
         run: npm run test:e2e
+
+      # In the interest of not having to modify GitHub settings to update required
+      # builds for passing, I stuck this test here.
+      - name: Test v4 build
+        run: |
+          git fetch --tags
+          npm run build:v4
+          # ensure v4 build files exist:
+          test -f lib/docsify.js
+          test -f themes/pure.css
+          # ensure no git changes after building v4:
+          git diff --exit-code
+          npm run clean:v4
+          # ensure v4 build files are removed:
+          test ! -f lib/docsify.js
+          test ! -f themes/pure.css
+          # ensure no git changes after cleaning v4:
+          git diff --exit-code
+
       - name: Store artifacts
         uses: actions/upload-artifact@v6
         if: failure()

.gitignore

@@ -14,7 +14,11 @@ node_modules
 !.gitkeep
 
 # Output folder for the global build only
-dist
+dist/
+
+# Output folders for the legacy v4 build
+lib/
+themes/
 
 # TypeScript declaration files for standard ESM consumption
 src/**/*.d.ts

build/release.sh

@@ -27,6 +27,7 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   npm run build
   npm run test:update:snapshot
   npm run test
+  npm run build:v4 # builds legacy v4 lib/ and themes/ folders for backwards compat while people transition to v5.
 
   # Changelog
   npx conventional-changelog -p angular -i CHANGELOG.md -s
@@ -46,4 +47,6 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   else
     npm publish --tag "$RELEASE_TAG"
   fi
+
+  npm run clean:v4 # clean up legacy v4 build files
 fi

docs/quickstart.md

@@ -22,7 +22,7 @@ After the `init` is complete, you can see the file list in the `./docs` subdirec
 - `README.md` as the home page
 - `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore
 
-You can easily update the documentation in `./docs/README.md`, of course you can add [more pages](adding-pages.md).
+You can easily update the documentation in `./docs/README.md`, and of course you can add [more pages](adding-pages.md).
 
 ## Preview your site
 
@@ -76,9 +76,14 @@ Download or create an `index.html` template using the following markup:
 
 ### Specifying docsify versions
 
-> [!TIP] Note that in both of the examples below, docsify URLs will need to be manually updated when a new major version of docsify is released (e.g. `v5.x.x` => `v6.x.x`). Check the docsify website periodically to see if a new major version has been released.
+> [!TIP] Note that in both of the examples below, docsify URLs will need to be
+> manually updated when a new major version of docsify is released (e.g. `v5.x.x`
+> => `v6.x.x`). Check the docsify website periodically to see if a new major
+> version has been released.
 
-Specifying a major version in the URL (`@5`) will allow your site to receive non-breaking enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch" updates) automatically. This is the recommended way to load docsify resources.
+Specifying a major version in the URL (`@5`) will allow your site to receive
+non-breaking enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch"
+updates) automatically. This is the recommended way to load docsify resources.
 
 <!-- prettier-ignore -->
 ```html
@@ -89,7 +94,11 @@ Specifying a major version in the URL (`@5`) will allow your site to receive non
 <script src="//cdn.jsdelivr.net/npm/docsify@5"></script>
 ```
 
-If you prefer to lock docsify to a specific version, specify the full version after the `@` symbol in the URL. This is the safest way to ensure your site will look and behave the same way regardless of any changes made to future versions of docsify.
+If you'd like to ensure absolutely no possibility of changes that will break
+your site (non-major updates can unintentionally introduce breaking changes
+despite that they aim not to), specify the full version after the `@` symbol in
+the URL. This is the safest way to ensure your site will look and behave the
+same way regardless of any changes made to future versions of docsify.
 
 <!-- prettier-ignore -->
 ```html
@@ -100,9 +109,17 @@ If you prefer to lock docsify to a specific version, specify the full version af
 <script src="//cdn.jsdelivr.net/npm/docsify@5.0.0"></script>
 ```
 
+JSDelivr supports [npm-compatible semver ranges](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies),
+so you can also use version syntax such as `@^5.0.0` for the latest v5 release,
+`@5.0.x` for the latest v5.0 patch release (f.e. you will receive 5.0.4 but
+not 5.1.0), `@5.x` for the latest v5 minor and patch releases (which is
+effectively the same as `@5` and `@^5.0.0`), etc.
+
 ### Manually preview your site
 
-If you have Python installed on your system, you can easily use it to run a static server to preview your site.
+If you have Python installed on your system, you can easily use it to run a
+static server to preview your site instead of using `docsify serve` from
+`docsify-cli`.
 
 ```python
 # Python 2

package.json

@@ -3,7 +3,10 @@
   "version": "5.0.0-rc.3",
   "description": "A magical documentation generator.",
   "homepage": "https://docsify.js.org",
-  "repository": "github:docsifyjs/docsify",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docsifyjs/docsify.git"
+  },
   "authors": "https://github.com/docsifyjs/docsify/graphs/contributors",
   "license": "MIT",
   "collective": {
@@ -31,7 +34,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "lib",
+    "themes"
   ],
   "lint-staged": {
     "*.js": "eslint --fix"
@@ -93,8 +98,11 @@
     "build:emoji": "node ./build/emoji.js",
     "build:js": "rollup -c",
     "build:types": "tsc",
+    "build:v4": "git checkout release-v4 && npm clean-install && git checkout docs/emoji.md src/core/render/emoji-data.js && rimraf packages/ && git checkout - && npm clean-install && npm run build:v4:deprecate -- lib/docsify.js && npm run build:v4:deprecate -- lib/docsify.min.js",
+    "build:v4:deprecate": "echo ';console.warn(\"Docsify v4 is no longer supported. See https://docsify.js.org for the latest version.\")' >> ",
     "build": "run-s clean build:types build:js build:css build:css:min build:cover",
-    "clean": "rimraf --glob \"dist/**\" \"themes/**\" \"_playwright*/**\" \"src/**/*.d.ts\" \"src/**/*.d.ts.map\"",
+    "clean": "rimraf --glob \"dist/**\" \"_playwright*/**\" \"src/**/*.d.ts\" \"src/**/*.d.ts.map\"",
+    "clean:v4": "rimraf lib/ themes/",
     "dev": "run-p serve:dev watch:*",
     "docker:build:test": "npm run docker:cli -- build:test",
     "docker:build": "docker build -f Dockerfile -t docsify-test:local .",