From 1d8a35f7007102e1dd00eeec47deb20a675cdab6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Sat, 10 Jan 2026 12:11:50 -0800 Subject: [PATCH 01/11] Add v5 upgrade docs. --- docs/_sidebar.md | 4 ++ docs/v5-upgrade.md | 107 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/v5-upgrade.md 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..1c5e42075 --- /dev/null +++ b/docs/v5-upgrade.md @@ -0,0 +1,107 @@ +# 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 [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 `https://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) +- The v5 core theme can be customized using CSS variables - view [Customization](themes.md?id=customization) for more details. + +That's it! Your Docsify site should now be running on v5. \ No newline at end of file From 1a03d35ccdf0561dc6b34c2680d01f9af10c37ca Mon Sep 17 00:00:00 2001 From: Paul Hibbitts Date: Sun, 11 Jan 2026 08:05:40 -0800 Subject: [PATCH 02/11] Update v5-upgrade.md --- docs/v5-upgrade.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index 1c5e42075..da74cf72b 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -102,6 +102,7 @@ View [Classes](themes.md?id=classes) for more details. - 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) -- The v5 core theme can be customized using CSS variables - view [Customization](themes.md?id=customization) for more details. +- Custom CSS that targeted v4 theme-specific classes or elements may need to be updated for v5 +- The v5 core theme can be customized using CSS variables - view [Customization](themes.md?id=customization) for more details That's it! Your Docsify site should now be running on v5. \ No newline at end of file From 26714e537511e4716e1821da99f4c37a19d5583d Mon Sep 17 00:00:00 2001 From: Paul Hibbitts Date: Sun, 11 Jan 2026 08:26:25 -0800 Subject: [PATCH 03/11] Update v5-upgrade.md --- docs/v5-upgrade.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index da74cf72b..f36f33fb3 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -45,7 +45,7 @@ View [Themes](themes.md) for more details. This adds a chevron indicator to the sidebar. You can omit this if you prefer. -View [Classes](themes.md?id=classes) for more details. +View [Theme Classes](themes.md?id=classes) for more details. ### 3. Update the Main Docsify Script @@ -102,7 +102,7 @@ View [Classes](themes.md?id=classes) for more details. - 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) -- Custom CSS that targeted v4 theme-specific classes or elements may need to be updated for v5 -- The v5 core theme can be customized using CSS variables - view [Customization](themes.md?id=customization) for more details +- 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. \ No newline at end of file From a8cd3344862fe351cc3b7166db1b9f5059459915 Mon Sep 17 00:00:00 2001 From: Paul Hibbitts Date: Sun, 11 Jan 2026 16:16:07 -0800 Subject: [PATCH 04/11] Update v5-upgrade.md --- docs/v5-upgrade.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index f36f33fb3..61b903cb4 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -5,6 +5,7 @@ The main changes when upgrading a Docsify v4 site to v5 involve updating CDN URL ## Before You Begin Some older Docsify sites may use non-version-locked URLs like: + ```html ``` @@ -18,18 +19,31 @@ If your site uses URLs without `@4` or a specific version number, follow the sam **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. @@ -39,8 +53,9 @@ 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. @@ -50,6 +65,7 @@ View [Theme Classes](themes.md?id=classes) for more details. ### 3. Update the Main Docsify Script **Change:** + ```html @@ -57,6 +73,7 @@ View [Theme Classes](themes.md?id=classes) for more details. ``` **To:** + ```html ``` @@ -64,6 +81,7 @@ View [Theme Classes](themes.md?id=classes) for more details. ### 4. Update Plugin URLs **Search Plugin:** + ```html @@ -75,6 +93,7 @@ View [Theme Classes](themes.md?id=classes) for more details. ``` **Zoom Plugin:** + ```html @@ -86,6 +105,7 @@ View [Theme Classes](themes.md?id=classes) for more details. ``` **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 `https://cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js` @@ -105,4 +125,4 @@ View [Theme Classes](themes.md?id=classes) for more details. - 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. \ No newline at end of file +That's it! Your Docsify site should now be running on v5. From 1d73ba196a4586ea7bbdb783f63ee54a31961bca Mon Sep 17 00:00:00 2001 From: Paul Hibbitts Date: Sun, 11 Jan 2026 16:23:45 -0800 Subject: [PATCH 05/11] Update docs.test.js.snap --- test/integration/__snapshots__/docs.test.js.snap | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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`] = ` + " `; From b7ac81ac89690e0ae2ba61dfbeba1e152bf1a1be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:06:56 -0800 Subject: [PATCH 06/11] Update docs/v5-upgrade.md Co-authored-by: Luffy <52o@qq52o.cn> --- docs/v5-upgrade.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index 61b903cb4..d77507e38 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -36,12 +36,12 @@ If your site uses URLs without `@4` or a specific version number, follow the sam ``` From 56151a8fbf7023d78383c3dea44da7109b953b3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:07:09 -0800 Subject: [PATCH 07/11] Update docs/v5-upgrade.md Co-authored-by: Luffy <52o@qq52o.cn> --- docs/v5-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index d77507e38..6d7fde1d8 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -75,7 +75,7 @@ View [Theme Classes](themes.md?id=classes) for more details. **To:** ```html - + ``` ### 4. Update Plugin URLs From 2a045f6c8103cf872ced7d94948293c7b6403bba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:07:19 -0800 Subject: [PATCH 08/11] Update docs/v5-upgrade.md Co-authored-by: Luffy <52o@qq52o.cn> --- docs/v5-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index 6d7fde1d8..d71caf020 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -89,7 +89,7 @@ View [Theme Classes](themes.md?id=classes) for more details. - + ``` **Zoom Plugin:** From 01191999b247ea906cf227a1a39263eb0394f907 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:07:28 -0800 Subject: [PATCH 09/11] Update docs/v5-upgrade.md Co-authored-by: Luffy <52o@qq52o.cn> --- docs/v5-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index d71caf020..04f35b3da 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -101,7 +101,7 @@ View [Theme Classes](themes.md?id=classes) for more details. - + ``` **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: From a1b1351413124ef08bc11b551215367b820a440c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:07:37 -0800 Subject: [PATCH 10/11] Update docs/v5-upgrade.md Co-authored-by: Luffy <52o@qq52o.cn> --- docs/v5-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index 04f35b3da..815e6719e 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -108,7 +108,7 @@ View [Theme Classes](themes.md?id=classes) for more details. - 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 `https://cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js` +- 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 From 6c8228ac38bcdd3408c03c8621512d74e3ac8f57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20Hibbitts=20=F0=9F=8D=81?= Date: Mon, 12 Jan 2026 08:21:29 -0800 Subject: [PATCH 11/11] Update v5-upgrade.md --- docs/v5-upgrade.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/v5-upgrade.md b/docs/v5-upgrade.md index 815e6719e..cd30ce455 100644 --- a/docs/v5-upgrade.md +++ b/docs/v5-upgrade.md @@ -122,6 +122,7 @@ View [Theme Classes](themes.md?id=classes) for more details. - 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