Skip to content

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

Merged
sy-records merged 2 commits intodevelopfrom
v4-compat
Feb 5, 2026
Merged

chore: Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5.#2667
sy-records merged 2 commits intodevelopfrom
v4-compat

Conversation

@trusktr
Copy link
Member

@trusktr trusktr commented Jan 17, 2026

Summary

Changes:

  • add a build:v4 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 clean:v4 script to clean v4 build outputs
  • hook the v4 build/clean scripts into the build/release.sh script
  • test the v4 build and clean in CI

This makes is so that when we publish 5.0, the published files will include the legacy v4 lib/ and themes/ folders. This will prevent websites that are still using unversioned URLs (such as https://unpkg.com/docsify/lib/docsify.js, due to v4 docs and CLI instructing people to use unversioned URLs and the docsify-cli initializing projects with unversioned URLs) from breaking when we release 5.0. Existing v4 websites will simply continue to load the v4 files as if nothing changed despite that the library version will be v5 instead of v4, while new 5.0 users will opt into the new paths in the dist/ folder, will be instructed to use versioned URLs in our docs, and will have projects initialized by docsify-cli using versioned URLs by default.

Related issue, if any:

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, renaming)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • Documentation content changes
  • Other (please describe):

For any code change,

  • Related documentation has been updated, if needed
  • Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

  • Yes
  • No

Tested in the following browsers:

  • Chrome
  • Firefox
  • Safari
  • Edge

Copilot AI review requested due to automatic review settings January 17, 2026 20:44
@vercel
Copy link

vercel bot commented Jan 17, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docsify-preview Ready Ready Preview, Comment Feb 3, 2026 8:37am

npm publish --tag "$RELEASE_TAG"
fi

npm run clean:v4 # clean up legacy v4 build files
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sy-records now that release.sh is updated, can you try this out with a --dry run to verify it works? The dry run output will show which files would be published (without publishing).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

npm notice
npm notice 📦  docsify@5.0.0-rc.3
npm notice Tarball Contents
npm notice 1.1kB LICENSE
npm notice 3.6kB README.md
npm notice 345.1kB dist/docsify.js
npm notice 180.3kB dist/docsify.min.js
npm notice 547.9kB dist/docsify.min.js.map
npm notice 3.9kB dist/plugins/assets/front-matter-DccD0XLA.css
npm notice 3.9kB dist/plugins/assets/front-matter.min-DccD0XLA.css
npm notice 1.9kB dist/plugins/disqus.js
npm notice 1.1kB dist/plugins/disqus.min.js
npm notice 3.1kB dist/plugins/disqus.min.js.map
npm notice 96.8kB dist/plugins/emoji.js
npm notice 69.5kB dist/plugins/emoji.min.js
npm notice 145.8kB dist/plugins/emoji.min.js.map
npm notice 952B dist/plugins/external-script.js
npm notice 544B dist/plugins/external-script.min.js
npm notice 1.6kB dist/plugins/external-script.min.js.map
npm notice 14.8kB dist/plugins/front-matter.js
npm notice 5.3kB dist/plugins/front-matter.min.js
npm notice 23.1kB dist/plugins/front-matter.min.js.map
npm notice 1.2kB dist/plugins/ga.js
npm notice 707B dist/plugins/ga.min.js
npm notice 2.0kB dist/plugins/ga.min.js.map
npm notice 934B dist/plugins/gitalk.js
npm notice 640B dist/plugins/gitalk.min.js
npm notice 1.6kB dist/plugins/gitalk.min.js.map
npm notice 1.7kB dist/plugins/gtag.js
npm notice 901B dist/plugins/gtag.min.js
npm notice 3.1kB dist/plugins/gtag.min.js.map
npm notice 1.4kB dist/plugins/matomo.js
npm notice 873B dist/plugins/matomo.min.js
npm notice 2.3kB dist/plugins/matomo.min.js.map
npm notice 313.0kB dist/plugins/search.js
npm notice 149.3kB dist/plugins/search.min.js
npm notice 86.9kB dist/plugins/search.min.js.map
npm notice 23.4kB dist/plugins/zoom-image.js
npm notice 10.0kB dist/plugins/zoom-image.min.js
npm notice 34.2kB dist/plugins/zoom-image.min.js.map
npm notice 2.0kB dist/themes/addons/core-dark.css
npm notice 2.7kB dist/themes/addons/core-dark.css.map
npm notice 1.3kB dist/themes/addons/core-dark.min.css
npm notice 2.4kB dist/themes/addons/core-dark.min.css.map
npm notice 1.5kB dist/themes/addons/vue.css
npm notice 2.2kB dist/themes/addons/vue.css.map
npm notice 1.1kB dist/themes/addons/vue.min.css
npm notice 2.1kB dist/themes/addons/vue.min.css.map
npm notice 54.4kB dist/themes/core.css
npm notice 67.8kB dist/themes/core.css.map
npm notice 39.9kB dist/themes/core.min.css
npm notice 64.7kB dist/themes/core.min.css.map
npm notice 328.9kB lib/docsify.js
npm notice 160.7kB lib/docsify.min.js
npm notice 1.6kB lib/plugins/disqus.js
npm notice 953B lib/plugins/disqus.min.js
npm notice 86.5kB lib/plugins/emoji.js
npm notice 67.2kB lib/plugins/emoji.min.js
npm notice 768B lib/plugins/external-script.js
npm notice 406B lib/plugins/external-script.min.js
npm notice 14.6kB lib/plugins/front-matter.js
npm notice 5.0kB lib/plugins/front-matter.min.js
npm notice 970B lib/plugins/ga.js
npm notice 537B lib/plugins/ga.min.js
npm notice 714B lib/plugins/gitalk.js
npm notice 424B lib/plugins/gitalk.min.js
npm notice 1.1kB lib/plugins/matomo.js
npm notice 714B lib/plugins/matomo.min.js
npm notice 17.1kB lib/plugins/search.js
npm notice 8.2kB lib/plugins/search.min.js
npm notice 21.5kB lib/plugins/zoom-image.js
npm notice 9.4kB lib/plugins/zoom-image.min.js
npm notice 11.9kB lib/themes/buble.css
npm notice 12.8kB lib/themes/dark.css
npm notice 12.7kB lib/themes/dolphin.css
npm notice 8.8kB lib/themes/pure.css
npm notice 13.1kB lib/themes/vue.css
npm notice 5.3kB package.json
npm notice 2.8kB src/core/config.d.ts
npm notice 1.6kB src/core/config.d.ts.map
npm notice 6.3kB src/core/config.js
npm notice 4.6kB src/core/Docsify.d.ts
npm notice 572B src/core/Docsify.d.ts.map
npm notice 1.8kB src/core/Docsify.js
npm notice 3.8kB src/core/event/index.d.ts
npm notice 492B src/core/event/index.d.ts.map
npm notice 18.5kB src/core/event/index.js
npm notice 2.1kB src/core/fetch/index.d.ts
npm notice 537B src/core/fetch/index.d.ts.map
npm notice 8.6kB src/core/fetch/index.js
npm notice 87B src/core/global-api.d.ts
npm notice 117B src/core/global-api.d.ts.map
npm notice 507B src/core/global-api.js
npm notice 1.2kB src/core/globals.d.ts
npm notice 1.3kB src/core/globals.d.ts.map
npm notice 1.2kB src/core/globals.ts
npm notice 46B src/core/index.d.ts
npm notice 97B src/core/index.d.ts.map
npm notice 232B src/core/index.js
npm notice 1.1kB src/core/init/lifecycle.d.ts
npm notice 749B src/core/init/lifecycle.d.ts.map
npm notice 2.9kB src/core/init/lifecycle.js
npm notice 66B src/core/module.d.ts
npm notice 99B src/core/module.d.ts.map
npm notice 30B src/core/module.js
npm notice 79B src/core/module.min.js
npm notice 119B src/core/modules.d.ts
npm notice 183B src/core/modules.d.ts.map
npm notice 78B src/core/modules.ts
npm notice 2.1kB src/core/render/compiler.d.ts
npm notice 497B src/core/render/compiler.d.ts.map
npm notice 7.9kB src/core/render/compiler.js
npm notice 160B src/core/render/compiler/blockquote.d.ts
npm notice 120B src/core/render/compiler/blockquote.d.ts.map
npm notice 1.6kB src/core/render/compiler/blockquote.js
npm notice 190B src/core/render/compiler/code.d.ts
npm notice 108B src/core/render/compiler/code.d.ts.map
npm notice 711B src/core/render/compiler/code.js
npm notice 252B src/core/render/compiler/heading.d.ts
npm notice 118B src/core/render/compiler/heading.d.ts.map
npm notice 1.3kB src/core/render/compiler/heading.js
npm notice 250B src/core/render/compiler/image.d.ts
npm notice 114B src/core/render/compiler/image.d.ts.map
npm notice 1.2kB src/core/render/compiler/image.js
npm notice 323B src/core/render/compiler/link.d.ts
npm notice 114B src/core/render/compiler/link.d.ts.map
npm notice 1.9kB src/core/render/compiler/link.js
npm notice 495B src/core/render/compiler/media.d.ts
npm notice 164B src/core/render/compiler/media.d.ts.map
npm notice 744B src/core/render/compiler/media.js
npm notice 158B src/core/render/compiler/paragraph.d.ts
npm notice 117B src/core/render/compiler/paragraph.d.ts.map
npm notice 484B src/core/render/compiler/paragraph.js
npm notice 136B src/core/render/compiler/tableCell.d.ts
npm notice 116B src/core/render/compiler/tableCell.d.ts.map
npm notice 477B src/core/render/compiler/tableCell.js
npm notice 134B src/core/render/compiler/taskList.d.ts
npm notice 115B src/core/render/compiler/taskList.d.ts.map
npm notice 702B src/core/render/compiler/taskList.js
npm notice 141B src/core/render/compiler/taskListItem.d.ts
npm notice 123B src/core/render/compiler/taskListItem.d.ts.map
npm notice 1.1kB src/core/render/compiler/taskListItem.js
npm notice 179B src/core/render/embed.d.ts
npm notice 112B src/core/render/embed.d.ts.map
npm notice 6.8kB src/core/render/embed.js
npm notice 54.7kB src/core/render/emoji-data.d.ts
npm notice 107B src/core/render/emoji-data.d.ts.map
npm notice 84.9kB src/core/render/emoji-data.js
npm notice 99B src/core/render/emojify.d.ts
npm notice 113B src/core/render/emojify.d.ts.map
npm notice 1.6kB src/core/render/emojify.js
npm notice 378B src/core/render/gen-tree.d.ts
npm notice 129B src/core/render/gen-tree.d.ts.map
npm notice 707B src/core/render/gen-tree.js
npm notice 2.1kB src/core/render/index.d.ts
npm notice 652B src/core/render/index.d.ts.map
npm notice 18.9kB src/core/render/index.js
npm notice 378B src/core/render/progressbar.d.ts
npm notice 319B src/core/render/progressbar.d.ts.map
npm notice 1.2kB src/core/render/progressbar.js
npm notice 137B src/core/render/slugify.d.ts
npm notice 124B src/core/render/slugify.d.ts.map
npm notice 752B src/core/render/slugify.js
npm notice 936B src/core/render/tpl.d.ts
npm notice 236B src/core/render/tpl.d.ts.map
npm notice 4.6kB src/core/render/tpl.js
npm notice 1.4kB src/core/render/utils.d.ts
npm notice 418B src/core/render/utils.d.ts.map
npm notice 2.8kB src/core/render/utils.js
npm notice 689B src/core/router/history/base.d.ts
npm notice 324B src/core/router/history/base.d.ts.map
npm notice 2.9kB src/core/router/history/base.js
npm notice 598B src/core/router/history/hash.d.ts
npm notice 324B src/core/router/history/hash.d.ts.map
npm notice 3.1kB src/core/router/history/hash.js
npm notice 461B src/core/router/history/html5.d.ts
npm notice 251B src/core/router/history/html5.d.ts.map
npm notice 1.7kB src/core/router/history/html5.js
npm notice 766B src/core/router/index.d.ts
npm notice 404B src/core/router/index.d.ts.map
npm notice 1.5kB src/core/router/index.js
npm notice 606B src/core/router/util.d.ts
npm notice 267B src/core/router/util.d.ts.map
npm notice 2.9kB src/core/router/util.js
npm notice 1.1kB src/core/util/ajax.d.ts
npm notice 540B src/core/util/ajax.d.ts.map
npm notice 2.9kB src/core/util/ajax.js
npm notice 1.0kB src/core/util/core.d.ts
npm notice 318B src/core/util/core.d.ts.map
npm notice 2.0kB src/core/util/core.js
npm notice 3.0kB src/core/util/dom.d.ts
npm notice 786B src/core/util/dom.d.ts.map
npm notice 3.9kB src/core/util/dom.js
npm notice 109B src/core/util/env.d.ts
npm notice 114B src/core/util/env.d.ts.map
npm notice 274B src/core/util/env.js
npm notice 123B src/core/util/index.d.ts
npm notice 97B src/core/util/index.d.ts.map
npm notice 88B src/core/util/index.js
npm notice 330B src/core/util/prism.d.ts
npm notice 132B src/core/util/prism.d.ts.map
npm notice 6.9kB src/core/util/prism.js
npm notice 269B src/core/virtual-routes/exact-match.d.ts
npm notice 153B src/core/virtual-routes/exact-match.d.ts.map
npm notice 527B src/core/virtual-routes/exact-match.js
npm notice 1.8kB src/core/virtual-routes/index.d.ts
npm notice 583B src/core/virtual-routes/index.d.ts.map
npm notice 3.4kB src/core/virtual-routes/index.js
npm notice 581B src/core/virtual-routes/next.d.ts
npm notice 299B src/core/virtual-routes/next.d.ts.map
npm notice 572B src/core/virtual-routes/next.js
npm notice 47B src/plugins/disqus.d.ts
npm notice 99B src/plugins/disqus.d.ts.map
npm notice 1.5kB src/plugins/disqus.js
npm notice 46B src/plugins/emoji.d.ts
npm notice 97B src/plugins/emoji.d.ts.map
npm notice 486B src/plugins/emoji.js
npm notice 56B src/plugins/external-script.d.ts
npm notice 117B src/plugins/external-script.d.ts.map
npm notice 748B src/plugins/external-script.js
npm notice 46B src/plugins/front-matter/index.d.ts
npm notice 97B src/plugins/front-matter/index.d.ts.map
npm notice 592B src/plugins/front-matter/index.js
npm notice 238B src/plugins/front-matter/parser.d.ts
npm notice 117B src/plugins/front-matter/parser.d.ts.map
npm notice 1.1kB src/plugins/front-matter/parser.js
npm notice 92B src/plugins/front-matter/yaml.d.ts
npm notice 107B src/plugins/front-matter/yaml.d.ts.map
npm notice 12.1kB src/plugins/front-matter/yaml.js
npm notice 43B src/plugins/ga.d.ts
npm notice 91B src/plugins/ga.d.ts.map
npm notice 1.0kB src/plugins/ga.js
npm notice 47B src/plugins/gitalk.d.ts
npm notice 99B src/plugins/gitalk.d.ts.map
npm notice 757B src/plugins/gitalk.js
npm notice 45B src/plugins/gtag.d.ts
npm notice 95B src/plugins/gtag.d.ts.map
npm notice 1.7kB src/plugins/gtag.js
npm notice 47B src/plugins/matomo.d.ts
npm notice 99B src/plugins/matomo.d.ts.map
npm notice 1.2kB src/plugins/matomo.js
npm notice 137B src/plugins/search/component.d.ts
npm notice 127B src/plugins/search/component.d.ts.map
npm notice 4.1kB src/plugins/search/component.js
npm notice 46B src/plugins/search/index.d.ts
npm notice 97B src/plugins/search/index.d.ts.map
npm notice 2.7kB src/plugins/search/index.js
npm notice 126B src/plugins/search/markdown-to-txt.d.ts
npm notice 128B src/plugins/search/markdown-to-txt.d.ts.map
npm notice 4.7kB src/plugins/search/markdown-to-txt.js
npm notice 459B src/plugins/search/search.d.ts
npm notice 170B src/plugins/search/search.d.ts.map
npm notice 8.9kB src/plugins/search/search.js
npm notice 3.9kB src/plugins/search/style.css
npm notice 51B src/plugins/zoom-image.d.ts
npm notice 107B src/plugins/zoom-image.d.ts.map
npm notice 680B src/plugins/zoom-image.js
npm notice 1.8kB src/themes/addons/core-dark.css
npm notice 1.5kB src/themes/addons/vue.css
npm notice 30B src/themes/core.css
npm notice 302B src/themes/shared/__index.css
npm notice 2.8kB src/themes/shared/_app.css
npm notice 1.1kB src/themes/shared/_base.css
npm notice 4.7kB src/themes/shared/_classes.css
npm notice 1.4kB src/themes/shared/_coverpage.css
npm notice 6.7kB src/themes/shared/_elements.css
npm notice 8.7kB src/themes/shared/_markdown.css
npm notice 1.2kB src/themes/shared/_mq.css
npm notice 2.2kB src/themes/shared/_navbar.css
npm notice 6.1kB src/themes/shared/_sidebar.css
npm notice 1.2kB src/themes/shared/_syntax.css
npm notice 505B src/themes/shared/_util.css
npm notice 387B src/themes/shared/_vars-advanced.css
npm notice 12.7kB src/themes/shared/_vars.css
npm notice 15.0kB themes/buble.css
npm notice 16.0kB themes/dark.css
npm notice 15.8kB themes/dolphin.css
npm notice 11.2kB themes/pure.css
npm notice 16.3kB themes/vue.css
npm notice Tarball Details
npm notice name: docsify
npm notice version: 5.0.0-rc.3
npm notice filename: docsify-5.0.0-rc.3.tgz
npm notice package size: 861.6 kB
npm notice unpacked size: 3.6 MB
npm notice shasum: d13cac07c312114ae4c11a3bae27b4de8cf82968
npm notice integrity: sha512-/Fy/r1soz5oAt[...]AK5mv3zfhBH1A==
npm notice total files: 276

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds build infrastructure to maintain v4 backwards compatibility in the v5 release by building and publishing the legacy lib/ and themes/ folders alongside the new v5 dist/ folder. This prevents existing v4 sites using unversioned CDN URLs from breaking when v5 is published.

Changes:

  • Added v4 build and clean scripts to package.json
  • Integrated v4 build/clean into the release process
  • Added CI tests to verify v4 build and cleanup work correctly

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
package.json Adds build:v4, build:v4:deprecate, and clean:v4 scripts; includes lib/ and themes/ in published files
build/release.sh Integrates v4 build after tests and v4 cleanup after npm publish
.gitignore Adds lib/ and themes/ to ignored files
.github/workflows/test.yml Adds CI test to verify v4 build creates expected files and cleanup removes them
docs/quickstart.md Updates versioning documentation with improved formatting and additional semver examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@docsifyjs docsifyjs deleted a comment from Copilot AI Jan 17, 2026
@docsifyjs docsifyjs deleted a comment from Copilot AI Jan 17, 2026
@docsifyjs docsifyjs deleted a comment from Copilot AI Jan 17, 2026
@docsifyjs docsifyjs deleted a comment from Copilot AI Jan 17, 2026
@docsifyjs docsifyjs deleted a comment from Copilot AI Jan 17, 2026
package.json Outdated
"build:emoji": "node ./build/emoji.js",
"build:js": "rollup -c",
"build:types": "tsc",
"build:v4": "git checkout v4 && npm clean-install && git co 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",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sy-records note here, it relies on a new v4 tag. If we update v4 for any reason (f.e. a security patch of some really annoying and compelling bug without workaround that a user has and they can't migrate to 5.0 yet), then we should also update the v4 tag to point to the latest v4 version. That way this script will work without modification, and will simply build the latest v4 version.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the v4 tag; it should use a branch instead. There was previously a release-v4, which I will rename to v4.

…lity 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
package.json Outdated
"build:emoji": "node ./build/emoji.js",
"build:js": "rollup -c",
"build:types": "tsc",
"build:v4": "git checkout 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",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"build:v4": "git checkout 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": "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",

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the branch name consists solely of a version number (e.g., v4), it cannot be loaded via the CDN link: Failed to fetch docsifyjs/docs-zh@4 from GitHub.

@sy-records sy-records changed the title Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5. chore: Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5. Feb 3, 2026
@sy-records sy-records merged commit 7e29ca0 into develop Feb 5, 2026
8 checks passed
@sy-records sy-records deleted the v4-compat branch February 5, 2026 07:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants