diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 86ad48f6b..8344e6873 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -27,5 +27,9 @@
- [Embed Files](embed-files.md)
- [UI Kit](ui-kit.md)
+- Upgrading
+
+ - [v4 to v5](v5-upgrade.md)
+
* [Awesome docsify](awesome.md)
* [Changelog](changelog.md)
diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md
new file mode 100644
index 000000000..cd30ce455
--- /dev/null
+++ b/docs/v5-upgrade.md
@@ -0,0 +1,129 @@
+# Upgrading v4 to v5
+
+The main changes when upgrading a Docsify v4 site to v5 involve updating CDN URLs and theme files. Your configuration settings remain mostly the same, so the upgrade is fairly straightforward.
+
+## Before You Begin
+
+Some older Docsify sites may use non-version-locked URLs like:
+
+```html
+
+```
+
+If your site uses URLs without `@4` or a specific version number, follow the same steps below. You'll need to update both the version specifier and the path structure.
+
+## Step-by-Step Instructions
+
+### 1. Update the Theme CSS
+
+**Replace the theme (v4):**
+
+```html
+
+
+
+```
+
+**With this (v5):**
+
+```html
+
+
+
+
+```
+
+**Note:** If you were using a different v4 theme (buble, dark, pure), the v5 core theme replaces these, though Vue and Dark themes are available as add-ons if preferred.
+
+View [Themes](themes.md) for more details.
+
+### 2. Add Optional Body Class (for styling)
+
+**Update your opening body tag:**
+
+```html
+
+```
+
+This adds a chevron indicator to the sidebar. You can omit this if you prefer.
+
+View [Theme Classes](themes.md?id=classes) for more details.
+
+### 3. Update the Main Docsify Script
+
+**Change:**
+
+```html
+
+
+
+```
+
+**To:**
+
+```html
+
+```
+
+### 4. Update Plugin URLs
+
+**Search Plugin:**
+
+```html
+
+
+
+
+
+
+
+```
+
+**Zoom Plugin:**
+
+```html
+
+
+
+
+
+
+
+```
+
+**Note:** If you're using additional Docsify plugins (such as emoji, external-script, front-matter, etc.), you'll need to update those URLs as well following the same pattern:
+
+- Change `/lib/plugins/` to `/dist/plugins/`
+- Update version from `@4` (or non-versioned) to `@5`
+- Example: `//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js` becomes `//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js`
+
+## Key Differences Summary
+
+- **CDN Path**: Changed from `/lib/` to `/dist/`
+- **Version**: Updated from `@4` to `@5`
+- **Themes**: v5 uses a core theme (with optional add-ons available)
+- **Plugin Names**: `zoom-image` → `zoom`
+
+## Additional Notes
+
+- Your configuration in `window.$docsify` stays the same
+- All your markdown content remains unchanged
+- The upgrade is non-breaking for most sites (however, legacy browsers like Internet Explorer 11 are no longer supported)
+- To maintain the same visual styling as Docsify v4, the [Vue theme (Add-on)](themes.md?id=vue-theme-add-on) is available
+- Custom CSS targeting v4 theme-specific classes or elements may need to be updated for v5
+- The v5 core theme can be customized using CSS variables - view [Theme Customization](themes.md?id=customization) for more details
+
+That's it! Your Docsify site should now be running on v5.
diff --git a/test/integration/__snapshots__/docs.test.js.snap b/test/integration/__snapshots__/docs.test.js.snap
index 32f7a9c06..7f6203290 100644
--- a/test/integration/__snapshots__/docs.test.js.snap
+++ b/test/integration/__snapshots__/docs.test.js.snap
@@ -23,6 +23,6 @@ exports[`Docs Site sidebar renders and is unchanged 1`] = `