diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 81a77b7e3..000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: Bug report -about: Create a report to help us fix an issue ---- - - - -## Bug Report - -#### Steps to reproduce - - - -#### Current behaviour - - - -#### Expected behaviour - - - -#### Other relevant information - -- Docsify version: - - - -- [ ] Bug still occurs when all/other plugins are disabled? - -- Docsify plugins (if the bug happens when plugins enabled, please try to isolate the issue): - - - - - -#### Please create a reproducible sandbox - -[![Edit 307qqv236](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/307qqv236) - -#### Mention the docsify version in which this bug was not present (if any) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..5326336cc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,61 @@ +name: Bug Report +description: Submit a bug report. +labels: ['bug', 'Triage'] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! **Please write in English**. + Before creating an issue please make sure you are using the latest version of Docsify. + + - type: textarea + attributes: + label: Description + description: A clear and concise description of what the bug is, and why you consider it to be a bug. + validations: + required: true + + - type: textarea + attributes: + label: Expected behavior + description: A description of what you expected to happen. + validations: + required: true + - type: textarea + attributes: + label: Actual behavior + description: A description of what is actually happening. + validations: + required: true + - type: textarea + attributes: + 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): + placeholder: | + 1. Step 1 + 2. Step 2 + validations: + required: true + + - type: textarea + attributes: + label: Environment + description: | + Please provide the following information if relevant to the issue: + ```markdown + - Your OS: + - Node.js version: + - npm/yarn version: + - Browser version: + - Docsify version: + - Docsify plugins (if the bug happens when plugins enabled, please try to isolate the issue): + ``` + + - type: checkboxes + attributes: + label: Additional Information + options: + - label: Bug still occurs when all/other plugins are disabled? diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index cb840f656..000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project ---- - - - -## Feature request - -#### Problem or desire - - - -#### Proposal - - - -#### Implementation - - diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..50adeb402 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: Feature Request +description: Propose a new feature or improvement for this project. +labels: ['feature request', 'Triage'] + +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a feature! Please provide as much detail as possible to help us understand your idea. **Write in English.** + + - type: textarea + attributes: + label: Problem or Desire + description: What problem or need will this feature address? Why is it important? + validations: + required: true + + - type: textarea + attributes: + label: Proposal + description: What is your proposed solution? How should this feature work? + validations: + required: true + + - type: textarea + attributes: + label: Implementation Details + description: If you have any ideas about how this feature could be implemented, please share them here. + + - type: textarea + attributes: + label: Additional Context + description: Add any other context, screenshots, or references that might help us understand your request. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9e1aea115..e03dcea0c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,6 @@ - - ## Summary - + ## Related issue, if any: @@ -17,37 +8,28 @@ Provide **before/after** screenshots for any UI changes. ## What kind of change does this PR introduce? - - If you choose Other, describe it. ---> +- [ ] Bugfix +- [ ] Feature +- [ ] Code style update (formatting, renaming) +- [ ] Refactoring (no functional changes, no api changes) +- [ ] Build related changes +- [ ] Documentation content changes +- [ ] Other (please describe): ## For any code change, - - - [ ] Related documentation has been updated, if needed - [ ] Related tests have been added or updated, if needed ## Does this PR introduce a breaking change? - - -Yes -No - +- [ ] Yes +- [ ] No + ## Tested in the following browsers: - [ ] Chrome diff --git a/.github/workflows/emoji.yml b/.github/workflows/emoji.yml index 7e83197ef..77fb6ab1c 100644 --- a/.github/workflows/emoji.yml +++ b/.github/workflows/emoji.yml @@ -25,7 +25,7 @@ jobs: - name: Commit id: auto-commit-action - uses: stefanzweifel/git-auto-commit-action@v5 + uses: stefanzweifel/git-auto-commit-action@v6 with: commit_message: 'chore: Sync emoji data with GitHub emoji API' branch: sync-emoji diff --git a/.vscode/launch.json b/.vscode/launch.json index c9611c096..9d8baf872 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -9,15 +9,15 @@ "request": "launch", "name": "Run unit tests", "runtimeExecutable": "npm", - "runtimeArgs": ["test"], + "runtimeArgs": ["run", "test:jest"], "console": "integratedTerminal" }, { "type": "node", "request": "launch", "name": "Run current test file", - "runtimeExecutable": "npx", - "runtimeArgs": ["jest"], + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test:jest", "--"], "args": ["-i", "${relativeFile}", "--testPathIgnorePatterns"], "console": "integratedTerminal" }, @@ -26,9 +26,8 @@ "request": "launch", "name": "Run selected test name", "runtimeExecutable": "npm", - "runtimeArgs": ["run-script", "test"], + "runtimeArgs": ["run", "test:jest", "--"], "args": [ - "--", "-i", "${relativeFile}", "-t", @@ -41,8 +40,8 @@ "type": "node", "request": "launch", "name": "Update current test file snapshot(s)", - "runtimeExecutable": "npx", - "runtimeArgs": ["jest"], + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test:jest", "--"], "args": [ "-i", "${relativeFile}", @@ -55,10 +54,9 @@ "type": "node", "request": "launch", "name": "Update selected test name snapshot(s)", - "runtimeExecutable": "npx", - "runtimeArgs": ["jest"], + "runtimeExecutable": "npm", + "runtimeArgs": ["run", "test:jest", "--"], "args": [ - "--", "-i", "${relativeFile}", "-t", diff --git a/CHANGELOG.md b/CHANGELOG.md index 3db8d2c4e..9668acf67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,17 +1,44 @@ -# [5.0.0-rc.1](https://github.com/docsifyjs/docsify/compare/v4.13.1...v5.0.0-rc.1) (2025-05-27) +# [5.0.0-rc.2](https://github.com/docsifyjs/docsify/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2025-09-05) + + +### Bug Fixes + +* enhance focus handling ([#2595](https://github.com/docsifyjs/docsify/issues/2595)) ([22ac7e8](https://github.com/docsifyjs/docsify/commit/22ac7e855de24b13280e9904930e58af58dbd6a7)) +* enhance focus handling by adding smooth scroll to content area ([#2569](https://github.com/docsifyjs/docsify/issues/2569)) ([20d095b](https://github.com/docsifyjs/docsify/commit/20d095b53c827c4d0590dee5fd377ba21560d7fb)) +* escape HTML in search keywords ([#2586](https://github.com/docsifyjs/docsify/issues/2586)) ([743e9cb](https://github.com/docsifyjs/docsify/commit/743e9cb484cc70859a582fb74d78ea1f52ef2c2a)) +* exclude app-name-link from sidebar text overflow styling ([#2564](https://github.com/docsifyjs/docsify/issues/2564)) ([375c058](https://github.com/docsifyjs/docsify/commit/375c058e3e1b12f3507d97a41b3fd8d6c4e904b0)) +* handle hash navigation to prevent duplicate callbacks ([#2575](https://github.com/docsifyjs/docsify/issues/2575)) ([72569de](https://github.com/docsifyjs/docsify/commit/72569dee8db92a01e8de5448e05c32afbd090fb2)) +* heading link overflow style ([#2568](https://github.com/docsifyjs/docsify/issues/2568)) ([be21637](https://github.com/docsifyjs/docsify/commit/be2163725ae314de3aa9a56c1216ce8c774cfcc6)) +* improve slug generation ([#2581](https://github.com/docsifyjs/docsify/issues/2581)) ([9bc58c9](https://github.com/docsifyjs/docsify/commit/9bc58c9ca24db513a90a06752181954aab0628ca)) +* remove block display from anchor links to prevent layout issues ([#2576](https://github.com/docsifyjs/docsify/issues/2576)) ([6e45024](https://github.com/docsifyjs/docsify/commit/6e4502416886b9494cd7b510968c351c7e6fc3cd)) +* **sidebar:** remove ignored headings and children ([#2580](https://github.com/docsifyjs/docsify/issues/2580)) ([2a49bd0](https://github.com/docsifyjs/docsify/commit/2a49bd0aa4bb17eeb3d9f363c6f2b01e61e778ac)) +* update relative link handling ([#2579](https://github.com/docsifyjs/docsify/issues/2579)) ([eeacfcc](https://github.com/docsifyjs/docsify/commit/eeacfcce2a3df4e4146b5b54275553452b317352)) + + +### Features + +* GitHub style callouts ([#2487](https://github.com/docsifyjs/docsify/issues/2487)) ([2e59b0f](https://github.com/docsifyjs/docsify/commit/2e59b0f50cf8123b98e4c97c3053aa6985ae13a2)) +* support config helper multi keys if supported ([#2571](https://github.com/docsifyjs/docsify/issues/2571)) ([a2f734f](https://github.com/docsifyjs/docsify/commit/a2f734f223cae475aefe7d41995a2030a1f9c0a2)) +* support extract content between fragment markers from Markdown ([#2582](https://github.com/docsifyjs/docsify/issues/2582)) ([32aa74e](https://github.com/docsifyjs/docsify/commit/32aa74e0d2fcd89705e5c30fc8b8e2562e7b774e)) + + + +# Changelog + +## [5.0.0-rc.1](https://github.com/docsifyjs/docsify/compare/v4.13.1...v5.0.0-rc.1) (2025-05-27) ### Bug Fixes * auto header config heading generate func ([#2474](https://github.com/docsifyjs/docsify/issues/2474)) ([4bc5062](https://github.com/docsifyjs/docsify/commit/4bc5062fc13a3a43c7ed432f1b585fdab41f1447)) * carbon broken ([#2387](https://github.com/docsifyjs/docsify/issues/2387)) ([87fd55d](https://github.com/docsifyjs/docsify/commit/87fd55d7125539b929f3260fca92e666e988b6da)) -* **ci:** run test action for pull requsts ([#2445](https://github.com/docsifyjs/docsify/issues/2445)) ([15ed3b7](https://github.com/docsifyjs/docsify/commit/15ed3b76b00eac06cc4230b1f592993adf2a893b)) -* correct loadSider=false render structure issue ([#2470](https://github.com/docsifyjs/docsify/issues/2470)) ([7cbd532](https://github.com/docsifyjs/docsify/commit/7cbd5322d056bb87b4340bdb19909a9c32d19abb)) +* **ci:** run test action for pull requests ([#2445](https://github.com/docsifyjs/docsify/issues/2445)) ([15ed3b7](https://github.com/docsifyjs/docsify/commit/15ed3b76b00eac06cc4230b1f592993adf2a893b)) +* correct loadSidebar=false render structure issue ([#2470](https://github.com/docsifyjs/docsify/issues/2470)) ([7cbd532](https://github.com/docsifyjs/docsify/commit/7cbd5322d056bb87b4340bdb19909a9c32d19abb)) * dev mode hot reload and add sourcemaps ([#2402](https://github.com/docsifyjs/docsify/issues/2402)) ([947d8de](https://github.com/docsifyjs/docsify/commit/947d8decb8c5c62f3ce50d0c6ac0e27bb6c7a6b5)) * enhancement of isExternal ([#2093](https://github.com/docsifyjs/docsify/issues/2093)) ([7f13ba0](https://github.com/docsifyjs/docsify/commit/7f13ba0f9841776008d0707f027bd80c4e3cbf0c)) * fix cross-origin links in history router mode ([#1967](https://github.com/docsifyjs/docsify/issues/1967)) ([ef6905b](https://github.com/docsifyjs/docsify/commit/ef6905b53a5c1587c3ebf870f0d11ff111a2350d)) * fix dependabot.yml ([a321e83](https://github.com/docsifyjs/docsify/commit/a321e8373b3c6afc9d0b08714e34bd8bd68716d9)) -* fix docisify-render denpendency. ([#1915](https://github.com/docsifyjs/docsify/issues/1915)) ([c73f858](https://github.com/docsifyjs/docsify/commit/c73f8587b2f67e28c228e521518110ff504cefeb)) +* fix docsify-server-renderer dependency. ([#1915](https://github.com/docsifyjs/docsify/issues/1915)) ([c73f858](https://github.com/docsifyjs/docsify/commit/c73f8587b2f67e28c228e521518110ff504cefeb)) * fix id with pure number. ([#2021](https://github.com/docsifyjs/docsify/issues/2021)) ([f4f21a3](https://github.com/docsifyjs/docsify/commit/f4f21a3f74d265f16b1e658feda417bf851458da)) * genIndex error for search ([#1933](https://github.com/docsifyjs/docsify/issues/1933)) ([a8f9fc1](https://github.com/docsifyjs/docsify/commit/a8f9fc1d5f5c7808efe65e5ca9359f38014b1bcd)) * husky can not auto install issue after upgrade. ([#2325](https://github.com/docsifyjs/docsify/issues/2325)) ([cec43d7](https://github.com/docsifyjs/docsify/commit/cec43d71774556d38fa9746f4df4319a6ad768c2)) @@ -86,8 +113,8 @@ * Add escapeHtml for search ([#1551](https://github.com/docsifyjs/docsify/issues/1551)) ([c24f7f6](https://github.com/docsifyjs/docsify/commit/c24f7f6f0b87a87f6dd3755f69eb0969ebb029c9)) * allow also " inside of an embed ([ec16e4a](https://github.com/docsifyjs/docsify/commit/ec16e4a9d5718ac4f4c25bb3dcaea3b7551372e0)) * buble theme missing generic fallback font ([#1568](https://github.com/docsifyjs/docsify/issues/1568)) ([37d9f0e](https://github.com/docsifyjs/docsify/commit/37d9f0e1214276e93b2a11ed87390aafa1bdbcec)) -* Cannot read property 'classList' of null ([#1527](https://github.com/docsifyjs/docsify/issues/1527)) ([d6df2b8](https://github.com/docsifyjs/docsify/commit/d6df2b85a99371bb9a87402a10dd515bb734182e)), closes [/github.com/docsifyjs/docsify/pull/1527#issuecomment-793455105](https://github.com//github.com/docsifyjs/docsify/pull/1527/issues/issuecomment-793455105) -* Cannot read property 'tagName' of null ([#1655](https://github.com/docsifyjs/docsify/issues/1655)) ([c3cdadc](https://github.com/docsifyjs/docsify/commit/c3cdadc37137edcd9e219359973902d2fc8b66ff)), closes [#1154](https://github.com/docsifyjs/docsify/issues/1154) [/github.com/docsifyjs/docsify/blob/develop/src/core/router/history/html5.js#L25-L27](https://github.com//github.com/docsifyjs/docsify/blob/develop/src/core/router/history/html5.js/issues/L25-L27) [/github.com/docsifyjs/docsify/blob/develop/src/core/router/history/hash.js#L47-L49](https://github.com//github.com/docsifyjs/docsify/blob/develop/src/core/router/history/hash.js/issues/L47-L49) +* Cannot read property 'classList' of null ([#1527](https://github.com/docsifyjs/docsify/issues/1527)) ([d6df2b8](https://github.com/docsifyjs/docsify/commit/d6df2b85a99371bb9a87402a10dd515bb734182e)) +* Cannot read property 'tagName' of null ([#1655](https://github.com/docsifyjs/docsify/issues/1655)) ([c3cdadc](https://github.com/docsifyjs/docsify/commit/c3cdadc37137edcd9e219359973902d2fc8b66ff)) * upgrade debug from 4.3.2 to 4.3.3 ([#1692](https://github.com/docsifyjs/docsify/issues/1692)) ([40e7749](https://github.com/docsifyjs/docsify/commit/40e77490c68b4143c75dfaebcd0b7f640581306b)) * Upgrade docsify from 4.12.0 to 4.12.1 ([#1544](https://github.com/docsifyjs/docsify/issues/1544)) ([d607f6d](https://github.com/docsifyjs/docsify/commit/d607f6d71c35b50f586806a832f65061f5e3427e)) * upgrade dompurify from 2.2.6 to 2.2.7 ([#1552](https://github.com/docsifyjs/docsify/issues/1552)) ([407e4d4](https://github.com/docsifyjs/docsify/commit/407e4d4f3de78bebd639a3fdae751f8045728e57)) @@ -937,7 +964,7 @@ Fix the last release files has the old version marked... ### Bug Fixes -- get file path, fixed jrappen/sublime-distractionless/commit/81bfadd391428823191cc03eca956a2312e04d13#commitcomment-22427070 ([e8117e5](https://github.com/QingWei-Li/docsify/commit/e8117e5)), closes [jrappen/sublime-distractionless/commit/81bfadd391428823191cc03eca956a2312e04d13#commitcomment-22427070](https://github.com/jrappen/sublime-distractionless/commit/81bfadd391428823191cc03eca956a2312e04d13/issues/commitcomment-22427070) +- get file path ([e8117e5](https://github.com/QingWei-Li/docsify/commit/e8117e5)) ### Features @@ -1086,5 +1113,5 @@ Fix the last release files has the old version marked... ### Features - finish ssr ([3444884](https://github.com/QingWei-Li/docsify/commit/3444884)) -- init ocsify-server-renderer ([6dea685](https://github.com/QingWei-Li/docsify/commit/6dea685)) +- init docsify-server-renderer ([6dea685](https://github.com/QingWei-Li/docsify/commit/6dea685)) - support history mode ([f095eb8](https://github.com/QingWei-Li/docsify/commit/f095eb8)) diff --git a/build/emoji.js b/build/emoji.js index cb502fe42..0b019b7d7 100644 --- a/build/emoji.js +++ b/build/emoji.js @@ -75,7 +75,6 @@ function writeEmojiJS(emojiData) { const isExistingPage = fs.existsSync(filePaths.emojiJS); const emojiJS = isExistingPage && fs.readFileSync(filePaths.emojiJS, 'utf8'); const newEmojiJS = [ - '/* eslint-disable */\n', '// =============================================================================', '// DO NOT EDIT: This file is auto-generated by an /build/emoji.js', '// =============================================================================\n', diff --git a/build/release.sh b/build/release.sh index c1bef5747..ed6ab730a 100755 --- a/build/release.sh +++ b/build/release.sh @@ -7,13 +7,21 @@ else VERSION=$1 fi +RELEASE_TAG=${RELEASE_TAG:-""} + +if [[ -n "$RELEASE_TAG" && "$VERSION" != *"$RELEASE_TAG"* ]]; then + RELEASE_MSG="$VERSION ($RELEASE_TAG)" +else + RELEASE_MSG="$VERSION" +fi + read -p "Releasing $VERSION $RELEASE_TAG - are you sure? (y/n) " -n 1 -r echo if [[ $REPLY =~ ^[Yy]$ ]]; then echo "Releasing $VERSION ..." # Update version (don't commit or tag yet) - npm --no-git-tag-version version "$VERSION" --message "[release] $VERSION $RELEASE_TAG" + npm --no-git-tag-version version "$VERSION" # Build and test npm run build @@ -25,7 +33,7 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then # Commit all changes git add -A - git commit -m "[release] $VERSION $RELEASE_TAG" + git commit -m "[release] $RELEASE_MSG" # Tag and push git tag "v$VERSION" diff --git a/docs/_coverpage.md b/docs/_coverpage.md index e9292beaf..c7d8200f4 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -2,7 +2,7 @@ ![logo](_media/icon.svg) -# docsify 5.0.0-rc.1 +# docsify 5.0.0-rc.2 :id=docsify > A magical documentation site generator diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 37b6f32cf..86ad48f6b 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -27,5 +27,5 @@ - [Embed Files](embed-files.md) - [UI Kit](ui-kit.md) -- [Awesome docsify](awesome.md) -- [Changelog](changelog.md) +* [Awesome docsify](awesome.md) +* [Changelog](changelog.md) diff --git a/docs/adding-pages.md b/docs/adding-pages.md index 9cd6407dc..fde7872d5 100644 --- a/docs/adding-pages.md +++ b/docs/adding-pages.md @@ -67,7 +67,7 @@ To create section headers: You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. -!> Docsify only looks for `_sidebar.md` in the current folder, and uses that, otherwise it falls back to the one configured using `window.$docsify.loadSidebar` config. +> [!IMPORTANT] Docsify only looks for `_sidebar.md` in the current folder, and uses that, otherwise it falls back to the one configured using `window.$docsify.loadSidebar` config. Example file structure: @@ -98,7 +98,7 @@ You can specify `alias` to avoid unnecessary fallback. ``` -!> You can create a `README.md` file in a subdirectory to use it as the landing page for the route. +> [!IMPORTANT] You can create a `README.md` file in a subdirectory to use it as the landing page for the route. ## Set Page Titles from Sidebar Selection diff --git a/docs/cdn.md b/docs/cdn.md index 4167e29af..e4d38752e 100644 --- a/docs/cdn.md +++ b/docs/cdn.md @@ -29,7 +29,7 @@ Uncompressed resources are available by omitting the `.min` from the filename. Specifying the latest major version allows your site to receive all non-breaking enhancements ("minor" updates) and bug fixes ("patch" updates) as they are released. This is good option for those who prefer a zero-maintenance way of keeping their site up to date with minimal risk as new versions are published. -?> When a new major version is released, you will need to manually update the major version number after the `@` symbol in your CDN URLs. +> [!TIP] When a new major version is released, you will need to manually update the major version number after the `@` symbol in your CDN URLs. ```html @@ -44,7 +44,7 @@ Specifying the latest major version allows your site to receive all non-breaking Specifying an exact version prevents any future updates from affecting your site. This is good option for those who prefer to manually update their resources as new versions are published. -?> When a new version is released, you will need to manually update the version number after the `@` symbol in your CDN URLs. +> [!TIP] When a new version is released, you will need to manually update the version number after the `@` symbol in your CDN URLs. ```html diff --git a/docs/configuration.md b/docs/configuration.md index e4cc24e02..53810a35a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -72,7 +72,9 @@ window.$docsify = { - Type: `Boolean` - Default: `false` -If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML. See [#78](https://github.com/docsifyjs/docsify/issues/78). +If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML — but only if the page does not already contain an H1 heading. + +For more details, see [#78](https://github.com/docsifyjs/docsify/issues/78). ```js window.$docsify = { @@ -301,7 +303,7 @@ Key `bindings` are defined as case insensitive string values separated by `+`. M The `callback` function receive a [keydown event](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event) as an argument. -!> Let site visitors know your custom key bindings are available! If a binding is associated with a DOM element, consider inserting a `` element as a visual cue (e.g., alt + a) or adding [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) and [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attributes for hover/focus hints. +> [!IMPORTANT] Let site visitors know your custom key bindings are available! If a binding is associated with a DOM element, consider inserting a `` element as a visual cue (e.g., alt + a) or adding [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) and [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attributes for hover/focus hints. ```js window.$docsify = { @@ -376,7 +378,7 @@ window.$docsify = { Website logo as it appears in the sidebar. You can resize it using CSS. -!> Logo will only be visible if `name` prop is also set. See [name](#name) configuration. +> [!IMPORTANT] Logo will only be visible if `name` prop is also set. See [name](#name) configuration. ```js window.$docsify = { @@ -917,9 +919,9 @@ If you have a link to the homepage in the sidebar and want it to be shown as act For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131). -## themeColor ⚠️ +## themeColor ⚠️ :id=themecolor -!> Deprecated as of v5. Use the `--theme-color` [theme property](themes#theme-properties) to [customize](themes#customization) your theme color. +> [!IMPORTANT] Deprecated as of v5. Use the `--theme-color` [theme property](themes#theme-properties) to [customize](themes#customization) your theme color. - Type: `String` @@ -931,9 +933,9 @@ window.$docsify = { }; ``` -## topMargin ⚠️ +## topMargin ⚠️ :id=topmargin -!> Deprecated as of v5. Use the `--scroll-padding-top` [theme property](themes#theme-properties) to specify a scroll margin when using a sticky navbar. +> [!IMPORTANT] Deprecated as of v5. Use the `--scroll-padding-top` [theme property](themes#theme-properties) to specify a scroll margin when using a sticky navbar. - Type: `Number|String` - Default: `0` diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md index f0606b56c..8f2ad880f 100644 --- a/docs/custom-navbar.md +++ b/docs/custom-navbar.md @@ -4,7 +4,7 @@ If you need custom navigation, you can create a HTML-based navigation bar. -!> Note that documentation links begin with `#/`. +> [!IMPORTANT] Note that documentation links begin with `#/`. ```html @@ -51,7 +51,7 @@ To create drop-down menus: - [chinese](/zh-cn/) ``` -!> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. +> [!IMPORTANT] You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. `_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`. diff --git a/docs/deploy.md b/docs/deploy.md index b6a8e3b41..e0cd152b9 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -14,14 +14,14 @@ It is recommended that you save your files to the `./docs` subfolder of the `mai ![GitHub Pages](_images/deploy-github-pages.png) -!> You can also save files in the root directory and select `main branch`. -You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch) +> [!IMPORTANT] You can also save files in the root directory and select `main branch`. +> You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch) ## GitLab Pages If you are deploying your master branch, create a `.gitlab-ci.yml` with the following script: -?> The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop. +> [!TIP] The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop. ```YAML pages: @@ -37,11 +37,11 @@ pages: - master ``` -!> You can replace script with `- cp -r docs/. public`, if `./docs` is your Docsify subfolder. +> [!IMPORTANT] You can replace script with `- cp -r docs/. public`, if `./docs` is your Docsify subfolder. ## Firebase Hosting -!> You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account. +> [!IMPORTANT] You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account. Using a terminal, determine and navigate to the directory for your Firebase Project. This could be `~/Projects/Docs`, etc. From there, run `firebase init` and choose `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions. diff --git a/docs/embed-files.md b/docs/embed-files.md index 60172d8ae..175e95d2d 100644 --- a/docs/embed-files.md +++ b/docs/embed-files.md @@ -75,7 +75,7 @@ Example: If you embed the file as `iframe`, `audio` and `video`, then you may need to set the attributes of these tags. -?> Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be. +> [!TIP] Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be. ```md [filename](_media/example.mp4 ':include :type=video controls width=100%') @@ -101,13 +101,13 @@ Embedding any type of source code file, you can specify the highlighted language [](_media/example.html ':include :type=code text') -?> How to set highlight? You can see [here](language-highlight.md). +> [!TIP] How to set highlight? You can see [here](language-highlight.md). ## Embed a gist You can embed a gist as markdown content or as a code block - this is based on the approach at the start of [Embed Files](#embed-files) section, but uses a raw gist URL as the target. -?> **No** plugin or app config change is needed here to make this work. In fact, the "Embed" `script` tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow an external script. +> [!TIP] **No** plugin or app config change is needed here to make this work. In fact, the "Embed" `script` tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow an external script. ### Identify the gist's metadata @@ -132,7 +132,7 @@ Here are two examples based on the sample gist: - https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md - https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js -?> Alternatively, you can get a raw URL directly clicking the _Raw_ button on a gist file. But, if you use that approach, just be sure to **remove** the revision number between `raw/` and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will **not** show the latest content when the gist is updated. +> [!TIP] Alternatively, you can get a raw URL directly clicking the _Raw_ button on a gist file. But, if you use that approach, just be sure to **remove** the revision number between `raw/` and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will **not** show the latest content when the gist is updated. Continue with one of the sections below to embed the gist on a Docsify page. diff --git a/docs/helpers.md b/docs/helpers.md index 57eaa41d0..32ddae19a 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -6,35 +6,69 @@ docsify extends Markdown syntax to make your documents more readable. ## Callouts -### Important content +Docsify supports [GitHub style](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) callouts (also known as "admonitions" or "alerts"). -Important content like: + +> [!CAUTION] +> **Caution** callouts communicate negative potential consequences of an action. -```markdown -!> **Time** is money, my friend! -``` + +> [!IMPORTANT] +> **Important** callouts communicate information necessary for users to succeed. -is rendered as: + +> [!NOTE] +> **Note** callouts communicate information that users should take into account. -!> **Time** is money, my friend! + +> [!TIP] +> **Tip** callouts communicate optional information to help a user be more successful. -### Tips + +> [!WARNING] +> **Warning** callouts communicate potential risks user should be aware of. -General tips like: +**Markdown** + ```markdown -?> _TODO_ unit test +> [!CAUTION] +> **Caution** callouts communicate negative potential consequences of an action. + +> [!IMPORTANT] +> **Important** callouts communicate information necessary for users to succeed. + +> [!NOTE] +> **Note** callouts communicate information that users should take into account. + +> [!TIP] +> **Tip** callouts communicate optional information to help a user be more successful. + +> [!WARNING] +> **Warning** callouts communicate potential risks user should be aware of. ``` -are rendered as: +### Legacy Style ⚠️ + +The following Docsify v4 callout syntax has been deprecated and will be removed in a future version. -?> _TODO_ unit test +!> Legacy **Important** callouts are deprecated. + +?> Legacy **Tip** callouts are deprecated. + +**Markdown** + +```markdown +!> Legacy **Important** callouts are deprecated. + +?> Legacy **Tip** callouts are deprecated. +``` ## Link attributes ### disabled -```md +```markdown [link](/demo ':disabled') ``` @@ -42,7 +76,7 @@ are rendered as: Sometimes we will use some other relative path for the link, and we have to tell docsify that we don't need to compile this link. For example: -```md +```markdown [link](/demo/) ``` @@ -50,13 +84,13 @@ It will be compiled to `link` and will load `/demo/README Now you can do that -```md +```markdown [link](/demo/ ':ignore') ``` You will get `link`html. Do not worry, you can still set the title for the link. -```md +```markdown [link](/demo/ ':ignore title') link @@ -64,14 +98,14 @@ You will get `link`html. Do not worry, you can still set th ### target -```md +```markdown [link](/demo ':target=_blank') [link](/demo2 ':target=_self') ``` ## Task lists -```md +```markdown - [ ] foo - bar - [x] baz @@ -91,19 +125,23 @@ You will get `link`html. Do not worry, you can still set th ### Class names -```md +```markdown ![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass') + + + +![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass :class=anotherCssClass') ``` ### IDs -```md +```markdown ![logo](https://docsify.js.org/_media/icon.svg ':id=someCssId') ``` ### Sizes -```md +```markdown ![logo](https://docsify.js.org/_media/icon.svg ':size=WIDTHxHEIGHT') ![logo](https://docsify.js.org/_media/icon.svg ':size=50x100') ![logo](https://docsify.js.org/_media/icon.svg ':size=100') @@ -119,7 +157,7 @@ You will get `link`html. Do not worry, you can still set th ## Heading IDs -```md +```markdown ### Hello, world! :id=hello-world ``` diff --git a/docs/index.html b/docs/index.html index 40d2a3470..91487eb74 100644 --- a/docs/index.html +++ b/docs/index.html @@ -47,6 +47,12 @@ disabled /> + + +