feat: implement version checking for Docsify script URLs

[sy-records]

Summary

Warn users when Docsify is loaded from a URL that does not include a pinned version.

Unversioned CDN URLs may begin serving a future major release automatically, which can break existing documentation sites. Minor or patch releases may also introduce unexpected regressions.

When an unpinned Docsify URL is detected, Docsify now emits a single, prominent console.error containing the detected URL and guidance to pin a version.

Supported URL formats

The version check recognizes:

• Package versions:
  • docsify@5
  • docsify@5.0
  • docsify@5.0.0
  • docsify@5.0.0-rc.1
• Versioned paths:
  • /docsify/5.0.0/docsify.js
• Versioned filenames:
  • /docsify-5.0.0.js
• Version query parameters:
  • ?v=5.0.0
  • ?version=5.0.0

Known URL formats are supported for:

• jsDelivr
• unpkg
• BootCDN
• cdnjs

Self-hosted Docsify scripts are checked as well.

IIFE and ESM support

• Classic IIFE builds use document.currentScript, with the existing <script> lookup as a fallback.
• ESM builds use import.meta.url.
• The ESM implementation is compatible with the build configuration introduced in feat: add ESM configuration for Docsify #2751.
• Ordinary npm/application bundles are ignored when their output URL cannot be identified as a Docsify distribution, avoiding false-positive warnings.

Example warning

[Docsify] Unpinned version detected in the Docsify script URL: https://cdn.jsdelivr.net/npm/docsify/dist/docsify.js
This site WILL BREAK when that URL begins serving a future major version and may break unexpectedly on minor or patch updates. Pin Docsify to a version in the URL (for example, docsify@5.0.0).

The warning does not prevent Docsify from starting and is emitted at most once.

Testing

• Added unit coverage for:
  • jsDelivr, unpkg, BootCDN, and cdnjs
  • Major-only, minor, patch, and prerelease versions
  • Path, filename, and query-parameter versions
  • Unversioned URLs and @latest
  • Dates, cache values, hashes, and unrelated numbers
  • ESM distribution detection
  • npm/application bundle detection
  • Single-warning behavior
• Added an E2E test using a real unversioned Docsify script.
• Updated existing test URLs to use an explicitly pinned version.

Validation completed:

• Unit tests: 73 passed
• Integration tests: 74 passed
• Chromium E2E tests: 83 passed
• Firefox targeted E2E tests: 4 passed
• IIFE and simulated ESM builds passed
• ESLint, Prettier, and TypeScript checks passed

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

[vercel]

@sy-records is attempting to deploy a commit to the Docsify Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

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

Project	Deployment	Actions	Updated
docsify-preview	Ready	Preview	Sep 3, 2026 3:14am UTC