Skip to content

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

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.

Sign up for GitHub

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

Merged
sy-records merged 2 commits into from
Feb 5, 2026
+60 −9
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d56a608
Build and publish v4 lib/ and themes/ folders for backwards compatibi…
trusktr Jan 17, 2026
605af3e
fix: update repository field format in package.json
sy-records Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
6 changes: 5 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions build/release.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Member Author

@trusktr trusktr Jan 17, 2026

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

@sy-records sy-records Feb 3, 2026

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

fi
27 changes: 22 additions & 5 deletions docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
14 changes: 11 additions & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -31,7 +34,9 @@
},
"files": [
"dist",
"src"
"src",
"lib",
"themes"
],
"lint-staged": {
"*.js": "eslint --fix"
Expand Down Expand Up @@ -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 .",
Expand Down