[Release]: v5.1.0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -33,7 +33,7 @@ body:
       label: Steps to reproduce
       description: |
         A description with steps to reproduce the issue.
-        Provide a link to a public repository or create a reproducible [sandbox](https://codesandbox.io/s/307qqv236):
+        Provide a link to a public repository or create a reproducible [sandbox](https://sandbox.docsifyjs.org/):
       placeholder: |
         1. Step 1
         2. Step 2

.github/workflows/crowdin.yml

@@ -16,7 +16,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Crowdin push
-        uses: crowdin/github-action@v2
+        uses: crowdin/github-action@v3
         with:
           upload_sources: true
           upload_translations: false

.github/workflows/test.yml

@@ -96,7 +96,7 @@ jobs:
         uses: actions/upload-artifact@v7
         if: failure()
         with:
-          name: ${{ matrix.os }}-${{ matrix.node-version }}-artifacts
+          name: test-artifacts-${{ github.run_id }}-${{ github.run_attempt }}
           path: |
             _playwright-results/
             _playwright-report/

.husky/install.mjs

@@ -0,0 +1,6 @@
+// Skip Husky install in production and CI
+if (process.env.NODE_ENV === 'production' || process.env.CI === 'true') {
+  process.exit(0);
+}
+const husky = (await import('husky')).default;
+console.log(husky());

README.md

@@ -41,7 +41,7 @@ Docsify turns one or more Markdown files into a Website, with no build process r
 
 Get going fast by using a static web server or GitHub Pages with this ready-to-use [Docsify Template](https://github.com/docsifyjs/docsify-template), review the [quick start tutorial](https://docsify.js.org/#/quickstart) or jump right into a CodeSandbox example site with the button below.
 
-[![Edit 307qqv236](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/307qqv236)
+[![Edit in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://sandbox.docsifyjs.org/)
 
 ## Showcase
 

build/types.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const projectDir = path.join(import.meta.dirname, '..');
+const sourcePath = path.join(projectDir, 'src/core/module.d.ts');
+const outputDir = path.join(projectDir, 'dist');
+const outputNames = ['docsify.module.d.ts', 'docsify.module.min.d.ts'];
+
+const declaration = (await fs.readFile(sourcePath, 'utf8'))
+  .replaceAll('"./', '"../src/core/')
+  .replace(/\/\/# sourceMappingURL=.*\n?$/, '');
+
+await fs.mkdir(outputDir, { recursive: true });
+await Promise.all(
+  outputNames.map(outputName =>
+    fs.writeFile(path.join(outputDir, outputName), declaration),
+  ),
+);

docs/README.md

@@ -17,7 +17,7 @@ Docsify turns your Markdown files into a documentation website instantly. Unlike
 
 ## Examples
 
-Check out the [Showcase](https://github.com/docsifyjs/awesome-docsify#showcase) to see docsify in use.
+Check out the [Showcase](awesome?id=showcase) to see docsify in use.
 
 ## Donate
 

docs/cdn.md

@@ -10,7 +10,6 @@ Other CDNs are available and may be required in locations where jsDelivr is not
 
 - https://cdnjs.com/libraries/docsify
 - https://unpkg.com/browse/docsify/
-- https://www.bootcdn.cn/docsify/
 
 ## Specifying versions
 

docs/configuration.md

@@ -12,6 +12,21 @@ You can configure Docsify by defining `window.$docsify` as an object:
 </script>
 ```
 
+Docsify is also available as an ES module. Import `Docsify` from a CDN and pass
+the configuration object to a new `Docsify` instance:
+
+```html
+<script type="module">
+  import { Docsify } from '//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.module.min.js';
+
+  new Docsify({
+    repo: 'docsifyjs/docsify',
+    maxLevel: 3,
+    coverpage: true,
+  });
+</script>
+```
+
 The config can also be defined as a function, in which case the first argument is the Docsify `vm` instance. The function should return a config object. This can be useful for referencing `vm` in places like the markdown configuration:
 
 ```html
@@ -109,6 +124,37 @@ window.$docsify = {
 
 Determines if Docsify should handle uncaught _synchronous_ plugin errors automatically. This can prevent plugin errors from affecting docsify's ability to properly render live site content.
 
+## collapseSidebarGroups
+
+- Type: `Boolean`
+- Default: `false`
+
+Initially collapses all root sidebar groups when `collapsibleSidebarGroups` is
+enabled. Visitors can still expand and collapse each group by selecting its
+title. Their choices are preserved while navigating between pages.
+
+```js
+window.$docsify = {
+  collapseSidebarGroups: true,
+  collapsibleSidebarGroups: true,
+};
+```
+
+## collapsibleSidebarGroups
+
+- Type: `Boolean`
+- Default: `false`
+
+Enables visitors to expand and collapse root sidebar groups by selecting their
+titles or using the <kbd>Enter</kbd> and <kbd>Space</kbd> keys. Enabling a
+sidebar chevron theme class also displays chevrons on these group titles.
+
+```js
+window.$docsify = {
+  collapsibleSidebarGroups: true,
+};
+```
+
 ## cornerExternalLinkTarget
 
 - Type: `String`
@@ -306,6 +352,20 @@ window.$docsify = {
 };
 ```
 
+## sidebarPosition
+
+- Type: `String`
+- Default: `'left'`
+
+Controls which side of the page displays the sidebar. Set this to `'right'` to
+place the sidebar and its toggle on the right.
+
+```js
+window.$docsify = {
+  sidebarPosition: 'right',
+};
+```
+
 ## homepage
 
 - Type: `String`
@@ -472,6 +532,21 @@ window.$docsify = {
 };
 ```
 
+## navbarPreservePath
+
+- Type: `Boolean`
+- Default: `false`
+
+If **true**, appends the current document path to navbar links that point to a language root. This makes it possible to switch languages while staying on the corresponding document.
+
+For example, when the current path is `/quickstart`, a navbar link to `/zh-cn/` becomes `/zh-cn/quickstart`.
+
+```js
+window.$docsify = {
+  navbarPreservePath: true,
+};
+```
+
 ## name
 
 - Type: `Boolean|String`

docs/deploy.md

@@ -256,3 +256,14 @@ To deploy your Docsify site using DeployHQ:
 Your Docsify site will be deployed to your server. You can enable automatic deployments to deploy on every Git push, or schedule deployments for specific times.
 
 For more information on advanced deployment features, see [DeployHQ's documentation](https://www.deployhq.com/support).
+
+## deed.page
+
+[deed.page](https://deed.page) hosts static sites published with one HTTP `PUT`. No account or build step is needed, so you can upload the `docs` folder as it is:
+
+```bash
+tar -C docs -czf site.tar.gz .
+curl -T site.tar.gz "https://deed.page/v1/sites?slug=my-docs"
+```
+
+The response includes the live `https://my-docs.deed.page/` URL and a token. To publish an update to the same slug, run the same command with `-H "Authorization: Bearer <token>"`. A single upload is capped at 4 MB; see the [deed.page docs](https://deed.page/docs) for larger sites.

docs/index.html

@@ -112,6 +112,7 @@
             'https://cdn.jsdelivr.net/gh/docsifyjs/docs-zh@main/$1',
         },
         auto2top: true,
+        collapsibleSidebarGroups: true,
         coverpage: true,
         executeScript: true,
         // hideSidebar: true,

docs/plugins.md

@@ -65,6 +65,11 @@ By default, the hyperlink on the current page is recognized and the content is s
       // You can provide a regexp to match prefixes. In this case,
       // the matching substring will be used to identify the index
       pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/,
+
+      // Show where each result comes from (default: 'none')
+      // 'page': the page title, e.g. "Guide"
+      // 'breadcrumb': the sidebar path, e.g. "Basics › Guide"
+      resultSource: 'none',
     },
   };
 </script>

docs/themes.md

@@ -110,13 +110,21 @@ Display a loading animation while waiting for Docsify to initialize.
 
 Display expand/collapse icons on page links in the sidebar.
 
+Root group titles display chevrons only when
+[`collapsibleSidebarGroups`](configuration.md?id=collapsiblesidebargroups) is
+enabled.
+
 <label>
   <input class="toggle" type="checkbox" value="sidebar-chevron-right" data-class data-group="sidebar-chevron"> Preview <code>sidebar-chevron-right</code>
 </label>
 <br>
 <label>
   <input class="toggle" type="checkbox" value="sidebar-chevron-left" data-class data-group="sidebar-chevron"> Preview <code>sidebar-chevron-left</code>
 </label>
+<br>
+<label>
+  <input class="toggle" type="checkbox" value="sidebar-chevron-root-hidden" data-class> Hide root-level chevrons with <code>sidebar-chevron-root-hidden</code>
+</label>
 
 <!-- prettier-ignore -->
 ```html
@@ -128,6 +136,14 @@ Display expand/collapse icons on page links in the sidebar.
 <body class="sidebar-chevron-left">
 ```
 
+To hide chevrons on all root-level page links and group titles while retaining
+chevrons on nested page links, add the `sidebar-chevron-root-hidden` class:
+
+<!-- prettier-ignore -->
+```html
+<body class="sidebar-chevron-right sidebar-chevron-root-hidden">
+```
+
 To prevent chevrons from displaying for specific page links, add a `no-chevron` class as follows:
 
 ```md

docs/v5-upgrade.md

@@ -101,7 +101,7 @@ View [Theme Classes](themes.md?id=classes) for more details.
 <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
 
 <!-- v5 -->
-<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/zoom.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/zoom-image.min.js"></script>
 ```
 
 **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:
@@ -110,12 +110,41 @@ View [Theme Classes](themes.md?id=classes) for more details.
 - 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`
 
+#### Plugin Authors
+
+If you've written a custom plugin that uses `window.Docsify.dom.toggleClass`, this helper has been removed in v5. Replace it with the native `Element.classList` API.
+
+Examples:
+
+```js
+// v4
+window.Docsify.dom.toggleClass(element, 'className');
+
+// v5
+element.classList.toggle('className');
+```
+
+```js
+// v4
+window.Docsify.dom.toggleClass(element, 'action', 'className');
+
+// v5
+element.classList.action('className');
+```
+
+```js
+// v4
+window.Docsify.dom.toggleClass(element, isDark ? 'add' : 'remove', 'dark');
+
+// v5
+element.classList[isDark ? 'add' : 'remove']('dark');
+```
+
 ## 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