[Release]: v5.0.0-rc.4

.github/workflows/crowdin.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Crowdin push
         uses: crowdin/github-action@v2

.github/workflows/emoji.yml

@@ -10,9 +10,9 @@ jobs:
     if: github.repository == 'docsifyjs/docsify'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: latest
           cache: 'npm'
@@ -25,7 +25,7 @@ jobs:
 
       - name: Commit
         id: auto-commit-action
-        uses: stefanzweifel/git-auto-commit-action@v6
+        uses: stefanzweifel/git-auto-commit-action@v7
         with:
           commit_message: 'chore: Sync emoji data with GitHub emoji API'
           branch: sync-emoji

.github/workflows/test.yml

@@ -14,9 +14,9 @@ jobs:
       matrix:
         node-version: ['lts/*']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
@@ -35,9 +35,9 @@ jobs:
         node-version: ['lts/*']
         os: ['macos-latest', 'ubuntu-latest', 'windows-latest']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
@@ -49,16 +49,18 @@ jobs:
         run: npm run test:unit -- --ci --runInBand
       - name: Integration Tests
         run: npm run test:integration -- --ci --runInBand
+      - name: Consumption Tests
+        run: npm run test:consume-types
 
   test-playwright:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         node-version: ['lts/*']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
@@ -70,8 +72,27 @@ jobs:
         run: npx playwright install --with-deps
       - name: E2E Tests (Playwright)
         run: npm run test:e2e
+
+      # In the interest of not having to modify GitHub settings to update required
+      # builds for passing, I stuck this test here.
+      - name: Test v4 build
+        run: |
+          git fetch --tags
+          npm run build:v4
+          # ensure v4 build files exist:
+          test -f lib/docsify.js
+          test -f themes/pure.css
+          # ensure no git changes after building v4:
+          git diff --exit-code
+          npm run clean:v4
+          # ensure v4 build files are removed:
+          test ! -f lib/docsify.js
+          test ! -f themes/pure.css
+          # ensure no git changes after cleaning v4:
+          git diff --exit-code
+
       - name: Store artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: failure()
         with:
           name: ${{ matrix.os }}-${{ matrix.node-version }}-artifacts

.gitignore

@@ -4,8 +4,6 @@
 .vercel
 _playwright-report
 _playwright-results
-dist
-lib
 node_modules
 
 # Files
@@ -14,3 +12,14 @@ node_modules
 
 # Exceptions
 !.gitkeep
+
+# Output folder for the global build only
+dist/
+
+# Output folders for the legacy v4 build
+lib/
+themes/
+
+# TypeScript declaration files for standard ESM consumption
+src/**/*.d.ts
+src/**/*.d.ts.map

.prettierignore

@@ -8,4 +8,4 @@ _vars.css
 _vars-advanced.css
 CHANGELOG.md
 emoji-data.*
-HISTORY.md
+HISTORY.md

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
   "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "cSpell.words": ["coverpage"]
+  "cSpell.words": ["coverpage"],
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

CONTRIBUTING.md

@@ -9,7 +9,7 @@ We welcome any type of contribution, not only code. You can help with
 - **QA**: file bug reports, the more details you can give the better (e.g. screenshots with the console open)
 - **Marketing**: writing blog posts, howto's, printing stickers, ...
 - **Community**: presenting the project at meetups, organizing a dedicated meetup for the local community, ...
-- **Code**: take a look at the [open issues](issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters. It helps us triage them.
+- **Code**: take a look at the [open issues](https://github.com/docsifyjs/docsify/issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters. It helps us triage them.
 - **Money**: we welcome financial contributions in full transparency on our [open collective](https://opencollective.com/docsify).
 
 ## Your First Contribution
@@ -70,7 +70,7 @@ Anyone can file an expense. If the expense makes sense for the development of th
 
 ## Questions
 
-If you have any questions, create an [issue](issue) (protip: do a quick search first to see if someone else didn't ask the same question before!).
+If you have any questions, create an [issue](https://github.com/docsifyjs/docsify/issues) (protip: do a quick search first to see if someone else didn't ask the same question before!).
 You can also reach us at hello@docsify.opencollective.com.
 
 ## Credits

README.md

@@ -30,7 +30,7 @@ Docsify turns one or more Markdown files into a Website, with no build process r
 
 ## Features
 
-- No statically built html files
+- No statically built HTML files
 - Simple and lightweight
 - Smart full-text search plugin
 - Multiple themes

build/release.sh

@@ -27,6 +27,7 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   npm run build
   npm run test:update:snapshot
   npm run test
+  npm run build:v4 # builds legacy v4 lib/ and themes/ folders for backwards compat while people transition to v5.
 
   # Changelog
   npx conventional-changelog -p angular -i CHANGELOG.md -s
@@ -46,4 +47,6 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
   else
     npm publish --tag "$RELEASE_TAG"
   fi
+
+  npm run clean:v4 # clean up legacy v4 build files
 fi

docs/README.md

@@ -4,13 +4,11 @@
 
 ## What it is
 
-Docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. Instead, it smartly loads and parses your Markdown files and displays them as a website. To start using it, all you need to do is create an `index.html` and [deploy it on GitHub Pages](deploy.md).
-
-See the [Quick start](quickstart.md) guide for more details.
+Docsify turns your Markdown files into a documentation website instantly. Unlike most other documentation site generator tools, it doesn't need to build HTML files. Instead, it dynamically loads and parses your Markdown files and displays them as a website. To get started, create an `index.html` file and [deploy it on GitHub Pages](deploy.md) (for more details see the [Quick start](quickstart.md) guide).
 
 ## Features
 
-- No statically built html files
+- No statically built HTML files
 - Simple and lightweight
 - Smart full-text search plugin
 - Multiple themes

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)

docs/configuration.md

@@ -240,6 +240,22 @@ window.$docsify = {
 };
 ```
 
+## fallbackDefaultLanguage
+
+- Type: `String`
+- Default: `''`
+
+When a page is requested and it doesn't exist for the given locale, Docsify will fallback to the language specified by this option.
+
+For example, in the scenario described above, if `/de/overview` does not exist and `fallbackDefaultLanguage` is configured as `zh-cn`, Docsify will fetch `/zh-cn/overview` instead of `/overview`.
+
+```js
+window.$docsify = {
+  fallbackLanguages: ['fr', 'de'],
+  fallbackDefaultLanguage: 'zh-cn', // default: ''
+};
+```
+
 ## formatUpdated
 
 - Type: `String|Function`
@@ -262,7 +278,7 @@ window.$docsify = {
 ## hideSidebar
 
 - Type : `Boolean`
-- Default: `true`
+- Default: `false`
 
 This option will completely hide your sidebar and won't render any content on the side.
 
@@ -440,7 +456,7 @@ window.$docsify = {
 
 ## name
 
-- Type: `String`
+- Type: `Boolean | String`
 
 Website name as it appears in the sidebar.
 
@@ -458,6 +474,22 @@ window.$docsify = {
 };
 ```
 
+If `true`, the website name will be inferred from the document's `<title>` tag.
+
+```js
+window.$docsify = {
+  name: true,
+};
+```
+
+If `false` or empty, no name will be displayed.
+
+```js
+window.$docsify = {
+  name: false,
+};
+```
+
 ## nameLink
 
 - Type: `String`
@@ -636,6 +668,10 @@ window.$docsify = {
 };
 ```
 
+## plugins
+
+See [Plugins](./plugins.md).
+
 ## relativePath
 
 - Type: `Boolean`
@@ -690,6 +726,8 @@ window.$docsify = {
 };
 ```
 
+If undefined or empty, no GitHub corner will be displayed.
+
 ## requestHeaders
 
 - Type: `Object`
@@ -871,9 +909,9 @@ window.$docsify = {
 Determines if/how the site's [skip navigation link](https://webaim.org/techniques/skipnav/) will be rendered.
 
 ```js
-// Render skip link for all routes (default)
+// Render skip link for all routes
 window.$docsify = {
-  skipLink: 'Skip to main content',
+  skipLink: 'Skip to content',
 };
 ```
 
@@ -896,6 +934,13 @@ window.$docsify = {
 };
 ```
 
+```js
+// Use default
+window.$docsify = {
+  skipLink: true, // "Skip to main content"
+};
+```
+
 ## subMaxLevel
 
 - Type: `Number`

docs/deploy.md

@@ -213,3 +213,30 @@ You can deploy **Docsify** as a Static Site on [Kinsta](https://kinsta.com/stati
    - Publish directory: `docs`
 
 6. Click the **Create site**.
+
+## DeployHQ
+
+[DeployHQ](https://www.deployhq.com/) is a deployment automation platform that deploys your code to SSH/SFTP servers, FTP servers, cloud storage (Amazon S3, Cloudflare R2), and modern hosting platforms (Netlify, Heroku).
+
+> [!IMPORTANT] DeployHQ does not host your site. It automates deploying your Docsify files to your chosen hosting provider or server.
+
+To deploy your Docsify site using DeployHQ:
+
+1. Sign up for a [DeployHQ account](https://www.deployhq.com/) and verify your email.
+
+2. Create your first project by clicking on **Projects** and **New Project**. Connect your Git repository (GitHub, GitLab, Bitbucket, or any private repository). Authorize DeployHQ to access your repository.
+
+3. Add a server and enter your server details:
+
+   - Give your server a name
+   - Select your protocol (SSH/SFTP, FTP, or cloud platform)
+   - Enter your server hostname, username, and password/SSH key
+   - Set **Deployment Path** to your web root (e.g., `public_html/`)
+
+4. Since Docsify doesn't require a build step, you can deploy your files directly. If your Docsify files are in a `docs/` folder, configure the **Source Path** in your server settings to `docs/`.
+
+5. Click **Deploy Project**, then select your server and click **Deploy** to start your first deployment.
+
+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).

docs/embed-files.md

@@ -65,9 +65,21 @@ Sometimes you don't want to embed a whole file. Maybe because you need just a fe
 ```
 
 In your code file you need to surround the fragment between `/// [demo]` lines (before and after the fragment).
-Alternatively you can use `### [demo]`.
+Alternatively you can use `### [demo]`. By default, only identifiers are omitted. To omit the entire line containing the identifier in the fragment output, add the `:omitFragmentLine` option. This is useful if your code fragment is e.g. HTML and you want to hide the Docsify fragment identifier from showing in your HTML source. `<!-- /// [demo] -->` in your source file and `:omitFragmentLine` will make the `-->` not show up in your Docsify code fragment section.
 
-Example:
+Example: In the source file \_media/example.js, `/// [demo]` identifiers have been included:
+
+```markdown
+[filename](_media/example.js ':include :type=code')
+```
+
+[filename](_media/example.js ':include :type=code')
+
+Adding the `:fragment=demo` results in the following:
+
+```markdown
+[filename](_media/example.js ':include :type=code :fragment=demo')
+```
 
 [filename](_media/example.js ':include :type=code :fragment=demo')
 
@@ -82,10 +94,10 @@ If you embed the file as `iframe`, `audio` and `video`, then you may need to set
 ```
 
 ```markdown
-[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')
+[cinwell website](https://google.com ':include :type=iframe width=100% height=400px')
 ```
 
-[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')
+[cinwell website](https://google.com ':include :type=iframe width=100% height=400px')
 
 Did you see it? You only need to write directly. You can check [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) for these attributes.