diff --git a/_sidebar.md b/_sidebar.md index 5540b35..27d2c22 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -27,6 +27,5 @@ - [文件嵌入](zh-cn/embed-files.md) - [UI Kit](zh-cn/ui-kit.md) -- [Awesome docsify](zh-cn/awesome.md) - -- [Changelog](zh-cn/changelog.md) +* [Awesome docsify](zh-cn/awesome.md) +* [Changelog](zh-cn/changelog.md) diff --git a/adding-pages.md b/adding-pages.md index c3cd12d..b7bd8e4 100644 --- a/adding-pages.md +++ b/adding-pages.md @@ -67,7 +67,7 @@ docs/zh-cn/guide.md => http://domain.com/#/zh-cn/guide 需要在 `./docs` 目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。 -!> Docsify 只查找当前文件夹中的 `_sidebar.md`，并使用它，否则会返回到使用 `window.$docsify.loadSidebar` 配置。 +> [!IMPORTANT] Docsify 只查找当前文件夹中的 `_sidebar.md`，并使用它，否则会返回到使用 `window.$docsify.loadSidebar` 配置。 示例文件结构： @@ -98,7 +98,7 @@ docs/zh-cn/guide.md => http://domain.com/#/zh-cn/guide ``` -!> 你可以在一个子目录中创建一个 `README.md` 文件来作为路由的默认网页。 +> [!IMPORTANT] 你可以在一个子目录中创建一个 `README.md` 文件来作为路由的默认网页。 ## 用侧边栏中选定的条目名称作为页面标题 diff --git a/cdn.md b/cdn.md index 059a3b2..0781c26 100644 --- a/cdn.md +++ b/cdn.md @@ -29,7 +29,7 @@ Docsify 推荐 [jsDelivr](//cdn.jsdelivr.net) 为其首选的 CDN： 指定最新的主要版本允许你的网站在发布时接收所有非破坏性的增强("次级"更新)和错误修复("补丁"更新)。 对于那些倾向于零维护又可以随着新版本的发布更新其网站的风险最小化的人来说，这是一个好的选择。 -?> 发布新的主要版本时，你需要在你的 CDN URLs 中的 `@` 符号后手动更新主要版本号。 +> [!TIP] 发布新的主要版本时，你需要在你的 CDN URLs 中的 `@` 符号后手动更新主要版本号。 @@ -45,7 +45,7 @@ Docsify 推荐 [jsDelivr](//cdn.jsdelivr.net) 为其首选的 CDN： 指定一个准确的版本可以防止将来的任何更新影响你的网站。 对于那些愿意在发布新版本时手动更新资源的人来说，这是一个很好的选项。 -?> 新版本发布后，你需要在你的 CDN URLs 中的 '@' 符号后手动更新版本号。 +> [!TIP] 新版本发布后，你需要在你的 CDN URLs 中的 '@' 符号后手动更新版本号。 diff --git a/configuration.md b/configuration.md index 9ca465a..ba7f576 100644 --- a/configuration.md +++ b/configuration.md @@ -72,7 +72,9 @@ window.$docsify = { - 类型：`Boolean` - 默认：`false` -同时设置 `loadSidebar` 和 `autoHeader` 后，可以根据 `_sidebar.md` 的内容自动为每个页面增加标题。 参见 [#78](https://github.com/docsifyjs/docsify/issues/78)。 +如果同时启用了 `loadSidebar` 和 `autoHeader` 功能，则对于 `_sidebar.md`中的每个链接，都会在将其转换为 HTML 之前为页面预置一个标题，但前提是该页面尚未包含 H1 标题。 + +参见 [#78](https://github.com/docsifyjs/docsify/issues/78)。 ```js window.$docsify = { @@ -105,14 +107,14 @@ window.$docsify = { - 类型：`Boolean` - 默认：`true` -决定 Docsify 是否应自动处理未捕获的 _synchronous_ 插件错误。 这可以防止插件错误影响 docsify 正确呈现实时网站内容的能力。 +决定 Docsify 是否应自动处理未捕获的 _synchronous_ 插件错误。 这可以防止插件错误影响 docsify 正常渲染网站内容的能力。 ## cornerExternalLinkTarget - 类型：`String` - 默认：`'_blank'` -右上角外部链接的打开方式。 默认为 `'_blank'` （在新窗口或者标签页中打开） +右上角的外部链接打开方式。 默认为 `'_blank'` （在新窗口或者标签页中打开） ```js window.$docsify = { @@ -163,7 +165,7 @@ window.$docsify = { - 类型：`Boolean` - 默认：`null` -执行页面上的脚本。 仅解析第一个脚本标签（[demo](themes)）。 如果检测到 Vue ，默认情况下是 `true` 。 +执行页面上的脚本。 仅解析第一个脚本标签（[demo](zh-cn/themes)）。 如果检测到 Vue ，默认情况下是 `true` 。 ```js window.$docsify = { @@ -179,7 +181,7 @@ window.$docsify = { ``` -注意，如果运行的是外部脚本，例如嵌入的 jsfidle demo，请务必包含 [external-script](zh-cn/plugins.md?id=external-script) 插件。 +注意，如果运行的是外部脚本，例如嵌入的 jsfidle demo，请确保引入 [external-script](zh-cn/plugins.md?id=external-script) 插件。 ## ext @@ -212,7 +214,7 @@ window.$docsify = { - 类型：`String` - 默认：`'_blank'` -在 markdown 中打开外部链接的目标。 外部链接的打开方式。默认为 `'_blank'` （在新窗口或者标签页中打开） +在 markdown 中打开外部链接的目标。 默认为 `'_blank'` （在新窗口或者标签页中打开） ```js window.$docsify = { @@ -229,8 +231,8 @@ window.$docsify = { 示例： - 尝试获取 `/de/overview` 页面。 如果该页面存在，就会显示出来。 -- 如果不存在则尝试 `/overview`（取决于默认语言），如果存在即显示。 如果该页面存在，就会显示出来。 -- 然后显示 404 页面。 +- 然后尝试获取默认页面 `/overview`（取决于默认语言）。 如果该页面存在，就会显示出来。 +- 如果也不存在，显示404页面。 ```js window.$docsify = { @@ -262,7 +264,7 @@ window.$docsify = { - 类型：`Boolean` - 默认：`true` -该选项将完全隐藏侧边栏，不会在侧边显示任何内容。 +该选项将完全隐藏侧边栏，不会在侧边栏显示任何内容。 ```js window.$docsify = { @@ -297,11 +299,11 @@ window.$docsify = { 将组合键绑定到自定义回调函数。 -键 `bindings` 定义为用 `+` 分隔的大小写不敏感的字符串值。 修改键值包括 `alt`、`ctrl`、`meta` 和 `shift`。 非修饰符键值应与键盘事件的 [key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) 或 [code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) 值相匹配。 +键 `bindings` 定义为用 `+` 分隔的大小写不敏感的字符串值。 修饰符键值包括 `alt`、`ctrl`、`meta` 和 `shift`。 非修饰符键值应与键盘事件的 [key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) 或 [code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) 值相匹配。 `callback` 函数接收[按键事件](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event)作为参数。 -!> 让网站访问者知道你的自定义按键绑定功能可用！ 如果绑定与 DOM 元素相关联，可考虑插入一个 `` 元素作为视觉提示（如alt+a），或添加 [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) 和 [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) 属性作为悬停/焦点提示。 +> [!IMPORTANT] 让网站访问者知道你的自定义按键是可用的 ！ 如果绑定与 DOM 元素相关联，可考虑插入一个 `` 元素作为视觉提示（如alt+a），或添加 [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) 和 [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) 属性作为悬停/焦点提示。 ```js window.$docsify = { @@ -376,7 +378,7 @@ window.$docsify = { 在侧边栏显示的网站 Logo。 你可以使用 CSS 调整它的大小。 -!> 只有同时设置了 `name`，Logo 才会可见。 请参阅 [name](#name) 配置。 +> [!IMPORTANT] 只有同时设置了 `name`，Logo 才会可见。 请参阅 [name](#name) 配置。 ```js window.$docsify = { @@ -415,7 +417,7 @@ window.$docsify = { - 类型：`Number` - 默认：`6` -最大表格内容级别。 +内容级别的最大值。 ```js window.$docsify = { @@ -448,11 +450,11 @@ window.$docsify = { }; ``` -名称字段也可包含自定义 HTML，以方便定制： +name 项也可以包含自定义 HTML 代码来方便地定制： ```js window.$docsify = { - name: '<0>docsify', + name: 'docsify', }; ``` @@ -506,7 +508,7 @@ window.$docsify = { -1 -`false` 时为原生字符的图像： +`true` 时为原生表情符号字符的图像： 😄︎ @@ -532,7 +534,7 @@ window.$docsify = { - 类型：`Array` -有时我们不希望 docsify 处理我们的链接。 参考 [#203](https://github.com/docsifyjs/docsify/issues/203)。 我们可以通过指定字符串数组来跳过某些链接的编译。 每个字符串都会被转换成正则表达式 (`RegExp`)，链接的 _whole_ href 会与之匹配。 +有时我们不希望 docsify 处理我们的链接： 参见 [#203](https://github.com/docsifyjs/docsify/issues/203)。 我们可以通过指定字符串数组来跳过某些链接的编译。 每个字符串都会被转换成正则表达式 (`RegExp`)，链接的 _whole_ href 会与之匹配。 ```js window.$docsify = { @@ -584,7 +586,7 @@ window.$docsify = { - 类型：`Boolean|String|Object` - 默认：`false` -显示默认 "404 - Not Found" 消息： +显示默认 “404 - Not Found” 消息： ```js window.$docsify = { @@ -592,7 +594,7 @@ window.$docsify = { }; ``` -在找不到指定页面时加载 `_404.md`： +加载 `_404.md` 文件： ```js window.$docsify = { @@ -600,7 +602,7 @@ window.$docsify = { }; ``` -加载自定义404页面： +加载 404 页面的自定义路径： ```js window.$docsify = { @@ -608,7 +610,7 @@ window.$docsify = { }; ``` -加载正确的本地化过的404页面： +根据本地化情况加载正确的 404 页面： ```js window.$docsify = { @@ -725,42 +727,16 @@ window.$docsify = { }; ``` -对于静态部署的站点（如 在 GitHub 页面上）基于哈希的路由设置更简单。 对于可以重写 URL 的网站，基于历史记录的格式 -更好（特别是对于搜索引擎优化而言，基于哈希值的路由对搜索引擎并不 -那么友好）。 - -基于哈希值的路由选择意味着所有 URL 路径都将在 -地址栏中以 `/#/` 作为前缀。 这是一种技巧，它允许网站加载 `/index.html`，然后 -使用 `#` 后面的路径来决定加载哪些 markdown 文件。 例如， -一个完整的基于哈希值的 URL 可以如下所示： -`https://example.com/#/path/to/page`。 浏览器将实际加载 -`https://example.com`（假设你的静态服务器默认提供 -`index.html`，大多数服务器都是这样做的），然后 Docsify JavaScript 代码将 -查看 `/#/...`，并确定要加载和渲染的标记符文件。 -此外，点击链接时，Docsify 路由器会动态更改哈希值之后的 -内容。 无论如何，`location.pathname` 的值仍将是 -`/`。 当在浏览器中访问这样的 URL 时，哈希路径的部分_不会_被发送到服务器。 - -另一方面，基于历史的路由意味着 Docsify JavaScript 将使用 -[History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) -来动态更改 URL，而无需使用 `#`。 这意味着，搜索引擎将把所有网址 -视为"真实"网址，在浏览器中访问网址时，完整路径将被发送到 -服务器。 例如，URL 可能看起来像 -`https://example.com/path/to/page`。 浏览器将尝试直接从服务器加载完整的 URL -，而不仅仅是 `https://example.com`。 这样做的好处是这些类型的 URL 对搜索引擎更友好，可以被索引（耶！）。 但缺点是，你的服务器或 -存放网站文件的地方必须能够处理这些 URL。 各种静态 -网站托管服务允许配置"重写规则"，这样就可以配置 -服务器，使其无论访问 -的路径是什么，都始终发回 `/index.html`。 `location.pathname `的值将显示 `/path/to/page`，因为 -实际上已经发送到服务器。 - -简要说明：从 `hash` 路由开始（默认）。 如果你有冒险精神，可以学习 -如何配置服务器，然后切换到 `history` 模式，以获得更好的体验 -，URL 中不含 `#`，并进行搜索引擎优化。 - -> **注意** 如果使用 `routerMode: 'history'`，可能需要添加 -> [`alias`]（#alias），以便无论访问哪个路径，都能 -> 加载 `_sidebar.md` 和 `_navbar.md` 文件。 +对于静态部署的站点（如 在 GitHub 页面上）基于 hash 的路由设置更简单。 对于可以重写 URL 的网站，基于历史记录的格式更好（特别是对于搜索引擎优化而言，基于哈希值的路由对搜索引擎并不那么友好）。 + +基于 hash 值的路由选择意味着所有 URL 路径都将在地址栏中以 `/#/` 作为前缀。 这是一种技巧，它允许网站加载 `/index.html`，然后使用 `#` 后面的路径来决定加载哪些 markdown 文件。 例如，一个完整的基于 hash 值的 URL 可以如下所示：`https://example.com/#/path/to/page`。 浏览器将实际加载 `https://example.com`（假设你的静态服务器默认提供`index.html`，大多数服务器都是这样做的），然后 Docsify JavaScript 代码将查看 `/#/...`，并确定要加载和渲染的 markdown 文件。 +此外，点击链接时，Docsify 路由器会动态更改 hash 值之后的内容。 无论如何，`location.pathname` 的值仍将是 `/`。 当在浏览器中访问这样的 URL 时，hash 路径的部分 _不会_ 被发送到服务器。 + +另一方面，基于历史的路由意味着 Docsify JavaScript 将使用 [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) 来动态更改 URL，而无需使用 `#`。 这意味着，搜索引擎将把所有网址视为“真实”网址，在浏览器中访问网址时，完整路径将被发送到服务器。 例如，URL 可能看起来像 `https://example.com/path/to/page`。 浏览器将尝试直接从服务器加载完整的 URL，而不仅仅是 `https://example.com`。 这样做的好处是这些类型的 URL 对搜索引擎更友好，可以被索引（耶！）。 但缺点是，你的服务器或存放网站文件的地方必须能够处理这些 URL。 各种静态网站托管服务允许配置“重写规则”，这样就可以配置服务器，使其无论访问的路径是什么，都始终发回 `/index.html`。 `location.pathname` 的值将显示 `/path/to/page`，因为实际上已经发送到服务器。 + +太长不看版：优先使用 `hash` 路由（默认）。 如果你有冒险精神，可以学习如何配置服务器，然后切换到 `history` 模式，以获得更好的体验，URL 中不含 `#`，并进行搜索引擎优化。 + +> **注意** 如果使用 `routerMode: 'history'`，可能需要添加[`alias`](#alias)，以便无论访问哪个路径，都能加载 `_sidebar.md` 和 `_navbar.md` 文件。 > > ```js > window.$docsify = { @@ -895,7 +871,7 @@ window.$docsify = { - 类型：`Number` - 默认：`0` -在自定义侧边栏中添加目录 (TOC)。 +在自定义侧边栏中添加目录（TOC）。 ```js window.$docsify = { @@ -911,11 +887,11 @@ window.$docsify = { - [Another page](another.md) ``` -详见[#1131](https://github.com/docsifyjs/docsify/issues/1131)。 +参见 [#1131](https://github.com/docsifyjs/docsify/issues/1131)。 -## themeColor ⚠️ +## themeColor ⚠️ :id=themecolor -!> 自 v5 起已弃用。 使用 `--theme-color` [主题属性](zh-cn/themes#theme-properties) [自定义](zh-cn/themes#customization) 主题颜色。 +> [!IMPORTANT] 废弃于 v5。 使用 `--theme-color` [主题属性](zh-cn/themes#theme-properties) [自定义](zh-cn/themes#customization) 主题颜色。 - 类型：`String` @@ -927,14 +903,14 @@ window.$docsify = { }; ``` -## topMargin ⚠️ +## topMargin ⚠️ :id=topmargin -!> 自 v5 起已弃用。 在使用粘性导航栏时，使用 `--scroll-padding-top` [主题属性](zh-cn/themes#theme-properties) 指定滚动边距。 +> [!IMPORTANT] 废弃于 v5。 在使用粘性导航栏时，使用 `--scroll-padding-top` [主题属性](zh-cn/themes#theme-properties) 指定滚动边距。 - 类型：`Number|String` - 默认：`0` -在视口顶部添加滚动填充。 当你添加了一个粘性或"固定"元素，并希望自动滚动与元素底部对齐时，该功能非常有用。 +在视口顶部添加滚动填充。 当你添加了一个粘性或“固定”元素，并希望自动滚动与元素底部对齐时，该功能非常有用。 ```js window.$docsify = { @@ -953,9 +929,9 @@ window.$docsify = { vueComponents: { 'button-counter': { template: ` - <0> + `, data() { return { @@ -994,11 +970,11 @@ window.$docsify = { ``` ```markdown -<0> - <1>- +

+ {{ count }} - <2>+ - + +

``` @@ -1013,7 +989,7 @@ window.$docsify = { - 类型：`Object` -指定要挂载为 Vue 实例的 DOM 元素及其相关选项。 每次加载新页面时，Docsify 都会在主内容区域挂载第一个匹配元素。 挂载元素 `data` 是每个实例的唯一特性，不会在用户导航站点时持续存在。 +指定要挂载为 Vue 实例的 DOM 元素及其相关选项。 挂载元素是使用 [CSS 选择器](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) 作为键，包含 Vue 选项的对象作为值来指定的。 每次加载新页面时，Docsify 都会在主内容区域挂载第一个匹配元素。 挂载元素 `data` 是每个实例的唯一特性，不会在用户导航站点时持续存在。 ```js window.$docsify = { diff --git a/custom-navbar.md b/custom-navbar.md index 1b6628b..d2a159f 100644 --- a/custom-navbar.md +++ b/custom-navbar.md @@ -4,7 +4,7 @@ 如果你需要定制导航栏，可以用 HTML 创建一个导航栏。 -!> 注意：文档的链接都要以 `#/` 开头。 +> [!IMPORTANT] 注意：文档的链接以 `#/` 开头。 ```html @@ -51,7 +51,7 @@ - [简体中文](/zh-cn/) ``` -!> 你需要在 `./docs` 目录下创建一个 `.nojekyll` 文件，以防止 GitHub Pages 忽略下划线开头的文件。 +> [!IMPORTANT] 你需要在 `./docs` 目录下创建一个 `.nojekyll` 文件，以防止 GitHub Pages 忽略下划线开头的文件。 `_navbar.md` 会从每一级目录加载。 如果当前目录中没有 `_navbar.md`，则会返回上一级目录。 例如，如果当前路径是 `/guide/quick-start`，则将从 `/guide/_navbar.md` 加载 `_navbar.md`。 diff --git a/deploy.md b/deploy.md index 88c9f96..5da459a 100644 --- a/deploy.md +++ b/deploy.md @@ -14,14 +14,14 @@ GitHub Pages 支持从三个地方读取文件： ![GitHub Pages](../_images/deploy-github-pages.png) -!> 你也可以在根目录中保存文件并选择 `main branch` 。 -你需要在部署位置下放一个 `.nojekyll` 文件（比如 `/docs` 目录或者 gh-pages 分支） +> [!IMPORTANT] 你也可以在根目录中保存文件并选择 `main branch` 。 +> 你需要在部署位置下放一个 `.nojekyll` 文件（比如 `/docs` 目录或者 gh-pages 分支） ## GitLab Pages 如果你正在部署你的主分支, 在 `.gitlab-ci.yml` 中包含以下脚本： -?> `.public` 的解决方法是这样的，`cp` 不会无限循环的将 `public/` 复制到自身。 +> [!TIP] `.public` 的解决方法是这样的，`cp` 不会无限循环的将 `public/` 复制到自身。 ```YAML pages: @@ -37,11 +37,11 @@ pages: - master ``` -!> 你可以用 `- cp -r docs/. public` 替换脚本，如果 `./docs` 是你的 docsify 子文件夹。 +> !IMPORTANT] 你可以用 `- cp -r docs/. public` 替换脚本，如果 `./docs` 是你的 docsify 子文件夹。 ## Firebase 主机 -!> 你需要先使用谷歌账号登录 [Firebase 控制台](https://console.firebase.google.com)，然后使用 `npm i -g firebase-tools` 命令安装 Firebase CLI 。 +> [!IMPORTANT] 你需要先使用谷歌账号登录 [Firebase 控制台](https://console.firebase.google.com)，然后使用 `npm i -g firebase-tools` 命令安装 Firebase CLI 。 使用终端，确定并导航到你的 Firebase 项目目录。 这可能是 `~/Projects/Docs`，等等。 在这里执行 `firebase init` 命令，从菜单中选择 `Hosting`（使用**空格键**选择，**方向键**切换选项，**回车键**确认）。 遵照安装说明。 @@ -208,8 +208,8 @@ frontend: 5. 在构建设置过程中，Kinsta 会自动尝试填写**Build command**、**Node version** 和 **Publish directory**。 如果不会，请填写以下内容： - - Build command：留空 - - Node version：保留默认选择或特定版本（如 `18.16.0`） - - Publish directory：`docs` + - Build command：留空 + - Node version：保留默认选择或特定版本（如 `18.16.0`） + - Publish directory：`docs` 6. 点击**Create site**。 diff --git a/embed-files.md b/embed-files.md index 2f9c5f1..b715ec6 100644 --- a/embed-files.md +++ b/embed-files.md @@ -75,7 +75,7 @@ Front Matter 通常在 Jekyl 等博客系统中使用，用于定义文档的元 如果你嵌入文件是一个 `iframe`、`audio` 或者 `video`，你可以给这些标签设置属性。 -?> 注意，对于 `audio` 和 `video` 类型，默认情况下，对应添加 `controlls` 属性。 当你想要添加更多属性时，需要手动添加 `controls` 属性。 +> [!TIP] 注意，对于 `audio` 和 `video` 类型，默认情况下，对应添加 `controlls` 属性。 当你想要添加更多属性时，需要手动添加 `controls` 属性。 ```md [filename](../_media/example.mp4 ':include :type=video controls width=100%') @@ -101,13 +101,13 @@ Front Matter 通常在 Jekyl 等博客系统中使用，用于定义文档的元 [](../_media/example.html ":include :type=code text") -?> 如何设置高亮？ 你可以查看[此处](zh-cn/language-highlight.md)。 +> [!TIP] 如何设置高亮？ 你可以查看[此处](zh-cn/language-highlight.md)。 ## 嵌入 Gist 你可以将 Gist 作为 Markdown 内容或代码块嵌入。这是基于[嵌入文件](#embed-files)部分开头的方法，不过是嵌入一个原始的 Gist URL。 -?> **无需**更改插件或应用程序配置即可运行。 事实上，即使你使用插件或修改配置来允许加载外部脚本，从 Gist 复制的 Embed `script` 标签也_无法_加载。 +> [!TIP] **无需**更改插件或应用程序配置即可运行。 事实上，即使你使用插件或修改配置来允许加载外部脚本，从 Gist 复制的 Embed `script` 标签也_无法_加载。 ### 确定 Gist 的元数据 @@ -132,7 +132,7 @@ Front Matter 通常在 Jekyl 等博客系统中使用，用于定义文档的元 - https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md - https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js -?> 或者，你可以直接点击 Gist 文件上的 _Raw_ 按钮获取原始 URL。 但如果你使用这种方法， 请务必**移除** `raw/` 和文件名之间的版本号，以便 URL 与上面的模式相匹配。 否则，当 Gist 更新时，你的嵌入式 Gist 将**不会**显示最新内容。 +> [!TIP] 或者，你可以直接点击 Gist 文件上的 _Raw_ 按钮获取原始 URL。 但如果你使用这种方法， 请务必**移除** `raw/` 和文件名之间的版本号，以便 URL 与上面的模式相匹配。 否则，当 Gist 更新时，你的嵌入式 Gist 将**不会**显示最新内容。 继续下面的一个部分，将 Gist 嵌入到 Docsify 页面上。 diff --git a/helpers.md b/helpers.md index fbf53ae..02e25a2 100644 --- a/helpers.md +++ b/helpers.md @@ -6,35 +6,75 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 ## 标注 -### 强调内容 +Docsify 支持 [GitHub 风格](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) 标注（也称为“警告”或“警报”）。 -重要内容如： + -```markdown -!> **Time** is money, my friend! -``` +> [!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. -渲染为： + -!> **Time** is money, my friend! +> [!WARNING] +> **Warning** callouts communicate potential risks user should be aware of. -### 提示 +**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. ``` -渲染为： +### 传统风格 ⚠️ :id=legacy-style- -?> _TODO_ unit test +以下 Docsify v4 标注语法已被弃用，并将在未来版本中删除。 + +!> Legacy **Important** callouts are deprecated. + +?> Legacy **Tip** callouts are deprecated. + +**Markdown** + +```markdown +!> Legacy **Important** callouts are deprecated. + +?> Legacy **Tip** callouts are deprecated. +``` ## 链接属性 ### disabled -```md +```markdown [link](/demo ':disabled') ``` @@ -42,7 +82,7 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 有时候我们会把其他一些相对路径放到链接上，你必须告诉 docsify 你不需要编译这个链接。 例如： -```md +```markdown [link](/demo/) ``` @@ -50,13 +90,13 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 现在你可以做到这一点 -```md +```markdown [link](/demo/ ':ignore') ``` 你会得到 `link` html 代码。 不要担心，你仍然可以为链接设置标题。 -```md +```markdown [link](/demo/ ':ignore title') link @@ -64,14 +104,14 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 ### target -```md +```markdown [link](/demo ':target=_blank') [link](/demo2 ':target=_self') ``` ## 任务清单 -```md +```markdown - [ ] foo - bar - [x] baz @@ -91,19 +131,23 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 ### 类名 -```md +```markdown ![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass') + + + +![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass :class=anotherCssClass') ``` ### ID -```md +```markdown ![logo](https://docsify.js.org/_media/icon.svg ':id=someCssId') ``` ### 大小 -```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 +163,7 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。 ## 设置标题的 id 属性 -```md +```markdown ### 你好，世界！ :id=hello-world ``` diff --git a/language-highlight.md b/language-highlight.md index 0e41ca6..97fb7d4 100644 --- a/language-highlight.md +++ b/language-highlight.md @@ -57,7 +57,7 @@ function add(a, b) { 通过加载 Prism [语法文件](https://cdn.jsdelivr.net/npm/prismjs@1/components/)，可支持其他[语言](https://prismjs.com/#supported-languages)： -!> 必须在 Docsify 之后加载 Prism 语法文件。 +> [!IMPORTANT] 必须在 Docsify 之后加载 Prism 语法文件。 ```html @@ -79,7 +79,7 @@ function add(a, b) { Docsify 的官方[主题](zh-cn/themes)与 Prism 语法高亮主题兼容。 -!> Prism 主题必须在 Docsify 主题之后加载。 +> [!IMPORTANT] Prism 主题必须在 Docsify 主题之后加载。 ```html diff --git a/markdown.md b/markdown.md index 9de5e16..1ea3d28 100644 --- a/markdown.md +++ b/markdown.md @@ -15,7 +15,7 @@ window.$docsify = { }; ``` -?> 完整配置参数参考 [marked 文档](https://marked.js.org/#/USING_ADVANCED.md) +> [!TIP] 完整配置参数参考 [marked 文档](https://marked.js.org/#/USING_ADVANCED.md) 你可以完全自定义解析规则。 @@ -31,7 +31,7 @@ window.$docsify = { ## 支持 mermaid -!> 目前 docsify 不支持异步 mermaid 渲染（最新的 mermaid 版本是 `v9.3.0`）。 +> [!IMPORTANT] 目前 docsify 不支持异步 mermaid 渲染（最新的 mermaid 版本是 `v9.3.0`）。 ```js // diff --git a/plugins.md b/plugins.md index 4c93c78..1f84be5 100644 --- a/plugins.md +++ b/plugins.md @@ -125,7 +125,7 @@ 显示更多的表情符号短代码。 如果没有这个插件，Docsify 只能渲染数量有限的表情短代码。 -!> 自 v4.13 起已弃用。 Docsify 不再需要此插件来提供完整的 emoji 支持。 +> [!IMPORTANT] 废弃于 v4.13。 Docsify 不再需要此插件来提供完整的 emoji 支持。 ```html diff --git a/quickstart.md b/quickstart.md index 4b2c025..20cd584 100644 --- a/quickstart.md +++ b/quickstart.md @@ -32,7 +32,7 @@ docsify init ./docs docsify serve docs ``` -?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/docsifyjs/docsify-cli)。 +> [!TIP] 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/docsifyjs/docsify-cli)。 ## 手动初始化 @@ -77,7 +77,7 @@ docsify serve docs ### 指定 docsify 版本 -?> 注意：在下面两个例子中，当 docsify 发布新的主要版本时，需要手动更新 docsify URL（例如，`v5.x.x` => `v6.x.x`）。 定期检查 docsify 网站，以查看新的主要版本是否已发布。 +> [!TIP] 注意：在下面两个例子中，当 docsify 发布新的主要版本时，需要手动更新 docsify URL（例如，`v5.x.x` => `v6.x.x`）。 定期检查 docsify 网站，以查看新的主要版本是否已发布。 在 URL 中指定一个主要版本 (`@5`)，可使你的网站自动接收非破坏性增强（即 "minor" 更新）和错误修复（即 "patch" 更新）。 这是加载 docsify 资源的推荐方式。 @@ -117,32 +117,6 @@ cd docs && python -m SimpleHTTPServer 3000 cd docs && python -m http.server 3000 ``` -## Loading 提示 - -如果你想要，你可以在 docsify 开始渲染文档之前显示一个加载提示信息： - -```html - - -
Please wait...
-``` - -如果更改了 `el` 的配置，需要将该元素加上 `data-app` 属性： - -```html - - -
Please wait...
- - -``` - -对比 [el 设置](zh-cn/configuration#el)。 -