Skip to content

Commit 1d8a35f

Browse files
paulhibbittspaulhibbitts
committed
Add v5 upgrade docs.
1 parent 29ed781 commit 1d8a35f

File tree

2 files changed

+111
-0
lines changed

2 files changed

+111
-0
lines changed

‎docs/_sidebar.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,9 @@
2727
- [Embed Files](embed-files.md)
2828
- [UI Kit](ui-kit.md)
2929

30+
- Upgrading
31+
32+
- [v4 to v5](v5-upgrade.md)
33+
3034
* [Awesome docsify](awesome.md)
3135
* [Changelog](changelog.md)

‎docs/v5-upgrade.md‎

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

0 commit comments

Comments
 (0)