|
| 1 | +# Upgrading v4 to v5 |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Before You Begin |
| 6 | + |
| 7 | +Some older Docsify sites may use non-version-locked URLs like: |
| 8 | + |
| 9 | +```html |
| 10 | +<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> |
| 11 | +``` |
| 12 | + |
| 13 | +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. |
| 14 | + |
| 15 | +## Step-by-Step Instructions |
| 16 | + |
| 17 | +### 1. Update the Theme CSS |
| 18 | + |
| 19 | +**Replace the theme (v4):** |
| 20 | + |
| 21 | +```html |
| 22 | +<link |
| 23 | + rel="stylesheet" |
| 24 | + href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" |
| 25 | +/> |
| 26 | +<!-- OR if you have non-versioned URL: --> |
| 27 | +<link |
| 28 | + rel="stylesheet" |
| 29 | + href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" |
| 30 | +/> |
| 31 | +``` |
| 32 | + |
| 33 | +**With this (v5):** |
| 34 | + |
| 35 | +```html |
| 36 | +<!-- Core Theme --> |
| 37 | +<link |
| 38 | + rel="stylesheet" |
| 39 | + href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css" |
| 40 | +/> |
| 41 | +<!-- Optional: Dark Mode Support --> |
| 42 | +<link |
| 43 | + rel="stylesheet" |
| 44 | + href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" |
| 45 | + media="(prefers-color-scheme: dark)" |
| 46 | +/> |
| 47 | +``` |
| 48 | + |
| 49 | +**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. |
| 50 | + |
| 51 | +View [Themes](themes.md) for more details. |
| 52 | + |
| 53 | +### 2. Add Optional Body Class (for styling) |
| 54 | + |
| 55 | +**Update your opening body tag:** |
| 56 | + |
| 57 | +```html |
| 58 | +<body class="sidebar-chevron-right"></body> |
| 59 | +``` |
| 60 | + |
| 61 | +This adds a chevron indicator to the sidebar. You can omit this if you prefer. |
| 62 | + |
| 63 | +View [Theme Classes](themes.md?id=classes) for more details. |
| 64 | + |
| 65 | +### 3. Update the Main Docsify Script |
| 66 | + |
| 67 | +**Change:** |
| 68 | + |
| 69 | +```html |
| 70 | +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script> |
| 71 | +<!-- OR if you have non-versioned URL: --> |
| 72 | +<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> |
| 73 | +``` |
| 74 | + |
| 75 | +**To:** |
| 76 | + |
| 77 | +```html |
| 78 | +<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script> |
| 79 | +``` |
| 80 | + |
| 81 | +### 4. Update Plugin URLs |
| 82 | + |
| 83 | +**Search Plugin:** |
| 84 | + |
| 85 | +```html |
| 86 | +<!-- v4 --> |
| 87 | +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script> |
| 88 | +<!-- OR non-versioned: --> |
| 89 | +<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.js"></script> |
| 90 | + |
| 91 | +<!-- v5 --> |
| 92 | +<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/search.min.js"></script> |
| 93 | +``` |
| 94 | + |
| 95 | +**Zoom Plugin:** |
| 96 | + |
| 97 | +```html |
| 98 | +<!-- v4 --> |
| 99 | +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script> |
| 100 | +<!-- OR non-versioned: --> |
| 101 | +<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script> |
| 102 | + |
| 103 | +<!-- v5 --> |
| 104 | +<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/zoom.min.js"></script> |
| 105 | +``` |
| 106 | + |
| 107 | +**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: |
| 108 | + |
| 109 | +- Change `/lib/plugins/` to `/dist/plugins/` |
| 110 | +- Update version from `@4` (or non-versioned) to `@5` |
| 111 | +- Example: `//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js` becomes `//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js` |
| 112 | + |
| 113 | +## Key Differences Summary |
| 114 | + |
| 115 | +- **CDN Path**: Changed from `/lib/` to `/dist/` |
| 116 | +- **Version**: Updated from `@4` to `@5` |
| 117 | +- **Themes**: v5 uses a core theme (with optional add-ons available) |
| 118 | +- **Plugin Names**: `zoom-image` → `zoom` |
| 119 | + |
| 120 | +## Additional Notes |
| 121 | + |
| 122 | +- Your configuration in `window.$docsify` stays the same |
| 123 | +- All your markdown content remains unchanged |
| 124 | +- The upgrade is non-breaking for most sites (however, legacy browsers like Internet Explorer 11 are no longer supported) |
| 125 | +- To maintain the same visual styling as Docsify v4, the [Vue theme (Add-on)](themes.md?id=vue-theme-add-on) is available |
| 126 | +- Custom CSS targeting v4 theme-specific classes or elements may need to be updated for v5 |
| 127 | +- The v5 core theme can be customized using CSS variables - view [Theme Customization](themes.md?id=customization) for more details |
| 128 | + |
| 129 | +That's it! Your Docsify site should now be running on v5. |
0 commit comments