diff --git a/README.md b/README.md index 991d17c..cadf620 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,11 @@ ## 概述 -docsify 可以快速帮你生成文档网站。 不同于 GitBook 的地方是它不会生成静态的 `.html` 文件。 相反，它能智能加载和解析 Markdown 文件，并将其显示为网站。 要开始使用它，只需创建一个 `index.html` 并将其[部署到 GitHub Pages](zh-cn/deploy.md)。 - -查看[快速开始](zh-cn/quickstart.md)了解详情。 +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). ## 特性 -- 没有静态生成的 html 文件 +- No statically built HTML files - 简单和轻量 - 智能的全文搜索 - 提供多套主题 diff --git a/_sidebar.md b/_sidebar.md index 27d2c22..31a4ed5 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -27,5 +27,9 @@ - [文件嵌入](zh-cn/embed-files.md) - [UI Kit](zh-cn/ui-kit.md) +- 升级 + + - [v4 到 v5](zh-cn/v5-upgrade.md) + * [Awesome docsify](zh-cn/awesome.md) * [Changelog](zh-cn/changelog.md) diff --git a/configuration.md b/configuration.md index ba7f576..ea69a84 100644 --- a/configuration.md +++ b/configuration.md @@ -240,6 +240,22 @@ window.$docsify = { }; ``` +## fallbackDefaultLanguage + +- 类型：`String` +- 默认：`''` + +当请求的页面不存在给定的语言时，Docsify 将回退到此选项指定的语言。 + +例如，在上述情况下，如果 `/de/overview` 不存在，而 `fallbackDefaultLanguage` 被配置为 `zh-cn`，Docsify 将获取 `/zh-cn/overview` 而不是 `/overview`。 + +```js +window.$docsify = { + fallbackLanguages: ['fr', 'de'], + fallbackDefaultLanguage: 'zh-cn', // default: '' +}; +``` + ## formatUpdated - 类型：`String|Function` @@ -262,7 +278,7 @@ window.$docsify = { ## hideSidebar - 类型：`Boolean` -- 默认：`true` +- 默认：`false` 该选项将完全隐藏侧边栏，不会在侧边栏显示任何内容。 @@ -390,7 +406,7 @@ window.$docsify = { - 类型：`Function` -参考 [Markdown 配置](zh-cn/markdown.md)。 +请参见 [Markdown 配置](zh-cn/markdown.md)。 ```js window.$docsify = { @@ -440,7 +456,7 @@ window.$docsify = { ## name -- 类型：`String` +- 类型：`Boolean | String` 在侧边栏中显示的网站名称。 @@ -458,6 +474,22 @@ window.$docsify = { }; ``` +如果`true`, 网站名称将从文档的 `` 标签中推出。 + +```js +window.$docsify = { + name: true, +}; +``` + +如果 `false` 或为空，则不显示名称。 + +```js +window.$docsify = { + name: false, +}; +``` + ## nameLink - 类型：`String` @@ -518,7 +550,7 @@ window.$docsify = { <span class="emoji">👎︎</span> </output> -要渲染短代码作为文本，用“:”HTML实体替换`:`字符。 +要渲染短代码作为文本，请将 `:` 字符替换为 `:` HTML 实体。 ```markdown :100: @@ -636,6 +668,10 @@ window.$docsify = { }; ``` +## plugins + +请参见[插件列表](zh-cn/plugins.md)。 + ## relativePath - 类型：`Boolean` @@ -690,6 +726,8 @@ window.$docsify = { }; ``` +如果未定义或为空，则不显示 GitHub corner。 + ## requestHeaders - 类型：`Object` @@ -841,9 +879,9 @@ window.$docsify = { 决定是否/如何显示网站的 [skip navigation link](https://webaim.org/techniques/skipnav/)。 ```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', }; ``` @@ -866,6 +904,13 @@ window.$docsify = { }; ``` +```js +// Use default +window.$docsify = { + skipLink: true, // "Skip to main content" +}; +``` + ## subMaxLevel - 类型：`Number` diff --git a/deploy.md b/deploy.md index 5da459a..dd14ffe 100644 --- a/deploy.md +++ b/deploy.md @@ -213,3 +213,30 @@ frontend: - Publish directory：`docs` 6. 点击**Create site**。 + +## DeployHQ + +[DeployHQ](https://www.deployhq.com/) 是一个部署自动化平台，可将你的代码部署到 SSH/SFTP 服务器、FTP 服务器、云存储（亚马逊 S3、Cloudflare R2）和现代托管平台（Netlify、Heroku）。 + +> [!IMPORTANT] DeployHQ 不会托管你的网站。 它能自动将 Docsify 文件部署到你选择的托管服务提供商或服务器上。 + +使用 DeployHQ 部署 Docsify 网站： + +1. 注册 [DeployHQ 账户](https://www.deployhq.com/) 并验证你的电子邮件。 + +2. 点击 **Projects** 和 **New Project**，创建第一个项目。 连接 Git 仓库（GitHub、GitLab、Bitbucket 或任何私有仓库）。 授权 DeployHQ 访问你的版本库。 + +3. 添加服务器并输入服务器详细信息： + + - 给你的服务器一个名称 + - 选择协议（SSH/SFTP、FTP 或云平台） + - 输入服务器主机名、用户名和密码/SSH 密钥 + - 设置 **Deployment Path** 到你的 web 根目录(例如，`public_html/`) + +4. 由于 Docsify 不需要构建步骤，你可以直接部署文件。 如果你的 Docsify 文件在 `docs/` 文件夹中，配置你的服务器设置中的 **Source Path** 到 `docs/`。 + +5. 单击 **Deploy Project**，然后选择服务器并单击 **Deploy**，开始首次部署。 + +你的 Docsify 网站将部署到你的服务器上。 你可以启用自动部署功能，在每次 Git 推送时进行部署，也可以安排在特定时间进行部署。 + +有关高级部署功能的更多信息，请参阅 [DeployHQ 文档](https://www.deployhq.com/support)。 diff --git a/embed-files.md b/embed-files.md index b715ec6..0eb0b3f 100644 --- a/embed-files.md +++ b/embed-files.md @@ -65,9 +65,21 @@ Front Matter 通常在 Jekyl 等博客系统中使用，用于定义文档的元 ``` 在你的代码文件中，你需要用斜线 `/// [demo]` 包裹该片段（片段的前后都要有）。 -或者你也可以使用 `### [demo]`。 +或者你也可以使用 `### [demo]`。 默认情况下，只省略标识符。 要省略片段输出中包含标识符的整行，请添加 `:omitFragmentLine` 选项。 如你的代码片段是 HTML 等，而你想隐藏 Docsify 片段标识符，使其不显示在 HTML 源代码中，则此功能非常有用。 `<!-- /// [demo] -->` 在源文件中，而 `:omitFragmentLine` 将使 `-->` 不显示在 Docsify 代码片段中。 -示例： +示例：在源文件 \_media/example.js 中，包含了 `/// [demo]` 标识符： + +```markdown +[filename](../_media/example.js ':include :type=code') +``` + +[filename](../_media/example.js ":include :type=code") + +添加 `:fragment=demo` 的结果如下： + +```markdown +[filename](../_media/example.js ':include :type=code :fragment=demo') +``` [filename](../_media/example.js ":include :type=code :fragment=demo") diff --git a/plugins.md b/plugins.md index 1f84be5..f8fee55 100644 --- a/plugins.md +++ b/plugins.md @@ -1,5 +1,9 @@ # 插件列表 +这些是 Docsify 的内置和外部插件。 + +也可以参阅如何[编写插件](zh-cn/write-a-plugin.md)。 + ## 全文搜索 默认情况下，当前页面上的超链接会被识别，内容会被保存到 `IndexedDB`。 你也可以指定文件的路径。 @@ -26,7 +30,7 @@ insertBefore: '.sidebar-nav', // CSS selector in .sidebar scope maxAge: 86400000, // Expiration time, the default one day - paths: [], // or 'auto' + paths: [], // string[] of files to search in, or 'auto' for discovery based on your sidebar placeholder: 'Type to search', // Localization diff --git a/quickstart.md b/quickstart.md index 20cd584..34acd33 100644 --- a/quickstart.md +++ b/quickstart.md @@ -22,7 +22,7 @@ docsify init ./docs - `README.md` 会做为主页内容渲染 - `.nojekyll` 用于阻止 GitHub Pages 忽略掉下划线开头的文件 -直接编辑 `docs/README.md` 就能更新文档内容，当然也可以[添加更多页面](zh-cn/adding-pages)。 +直接编辑 `docs/README.md` 就能更新文档内容，当然也可以[添加更多页面](zh-cn/adding-pages.md)。 ## 本地预览 @@ -91,7 +91,7 @@ docsify serve docs <script src="//cdn.jsdelivr.net/npm/docsify@5"></script> ``` -如果你希望将 docsify 锁定到特定版本，请在 URL 中的 `@` 符号后指定完整版本。 这是最安全的方法，可确保无论 docsify 的未来版本如何更改，你的网站都将以相同的方式显示和运行。 +如果您想确保绝对不会出现会破坏网站的更改（非主要更新可能会无意中引入破坏性更改，尽管它们的目的不是这样），请在 URL 中的 `@` 符号后指定完整版本。 这是最安全的方法，可确保无论 docsify 的未来版本如何更改，你的网站都将以相同的方式显示和运行。 <!-- prettier-ignore --> @@ -103,9 +103,11 @@ docsify serve docs <script src="//cdn.jsdelivr.net/npm/docsify@5.0.0"></script> ``` +JSDelivr 支持 [npm-compatible semver ranges](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies)，因此也可以使用版本语法，例如 `@^5.0.0` 表示最新的 v5 版本，`@5.0.x` 表示最新的 v5.0 补丁版本（例如 你将收到 5.0.4，但不是 5.1.0），`@5.x` 表示最新的 v5 次版本和补丁版本（实际上与 `@5` 和 `@^5.0.0` 相同），等等。 + ### 手动预览你的网站 -如果你的系统里安装了 Python 的话，也可以很容易地启动一个静态服务器去预览你的网站。 +如果你的系统上安装了 Python，你可以很容易地使用它来运行静态服务器来预览你的网站，而不是使用 `docsify-cli` 中的 `docsify serve`。 ```python # Python 2 diff --git a/themes.md b/themes.md index 1cc3b59..63b24b2 100644 --- a/themes.md +++ b/themes.md @@ -11,7 +11,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css" /> ``` -## 主题附加组件 +## 主题附加组件 :id=theme-add-ons 主题附加组件与[核心主题](#core-theme)结合使用。 附加组件包含修改[主题属性](#theme-properties)值和/或添加自定义样式声明的 CSS 规则。 它们通常（但不总是）可以与其他附加组件一起使用。 @@ -27,7 +27,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <link rel="stylesheet" href="..." /> ``` -### 核心深色（附加组件） +### 核心深色（附加组件） :id=core-dark-add-on [核心主题](#core-theme)的深色模式样式。 只有在操作系统的暗模式激活时，才能通过指定 `media` 属性来应用样式。 @@ -67,7 +67,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" media="(prefers-color-scheme: dark)" /> ``` -### Vue 主题（附加组件） +### Vue 主题（附加组件） :id=vue-theme-add-on 备受欢迎的 Docsify v4 主题。 @@ -89,7 +89,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/vue.min.css" /> ``` -## 类 +## 类 :id=classes [核心主题](#core-theme)提供了多个 CSS 类，用于自定义 Docsify 网站。 这些类应用于 `index.html` 页面中的 `<body>` 元素。 @@ -99,7 +99,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <body class="..."> ``` -### 加载中 +### 加载中 :id=loading 在等待 Docsify 初始化时显示加载动画。 @@ -113,7 +113,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <div class="loading" style="margin: auto;"></div> </output> -### 侧边栏格线 +### 侧边栏格线 :id=sidebar-chevrons 在侧边栏的页面链接上显示展开/折叠图标。 @@ -154,7 +154,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 } ``` -### 侧边栏组 +### 侧边栏组 :id=sidebar-groups 在侧边栏的链接组之间添加视觉区分。 @@ -178,7 +178,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <body class="sidebar-group-underline"> ``` -### 侧边栏链接夹 +### 侧边栏链接夹 :id=sidebar-link-clamp 将多行侧边栏链接限制为单行，后加省略号。 @@ -193,7 +193,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <body class="sidebar-link-clamp"> ``` -### 侧边栏切换 +### 侧边栏切换 :id=sidebar-toggle 在侧边栏切换按钮中显示 "hamburger" 图标（三行），而不是默认的 "kebab" 图标。 @@ -219,7 +219,7 @@ Docsify "核心" 主题包含呈现 Docsify 网站所需的所有样式和[主 <body class="sidebar-toggle-hamburger"> ``` -## 定制 +## 定制 :id=customization Docsify 提供了[主题属性](#theme-properties)以简化对经常修改的样式的自定义。 @@ -323,19 +323,19 @@ Docsify 提供了[主题属性](#theme-properties)以简化对经常修改的样 > [!TIP] **主题和插件作者**：我们鼓励你利用这些自定义主题属性，并在你的项目中提供类似的自定义选项。 -### Common +### Common :id=common 以下是最常修改的主题属性。 [Advanced](#advanced) 主题属性也可以使用，但通常不需要修改。 [\_vars.css](https://raw.githubusercontent.com/docsifyjs/docsify/refs/heads/develop/src/themes/shared/_vars.css ":include") -### Advanced +### Advanced :id=advanced Advanced 主题属性也可供使用，但通常无需修改。 从 [common](#common) 主题属性导出的值，但也可根据需要明确设置。 [\_vars-advanced.css](https://raw.githubusercontent.com/docsifyjs/docsify/refs/heads/develop/src/themes/shared/_vars-advanced.css ":include") -## 社区 +## 社区 :id=community 有关其他社区主题，请参见 [Awesome Docsify](zh-cn/awesome)。 diff --git a/v5-upgrade.md b/v5-upgrade.md new file mode 100644 index 0000000..cca6d57 --- /dev/null +++ b/v5-upgrade.md @@ -0,0 +1,129 @@ +# 将 v4 升级到 v5 + +将 Docsify v4 网站升级到 v5 时的主要更改涉及更新 CDN URL 和主题文件。 你的配置设置基本保持不变，因此升级相当简单。 + +## 开始之前 + +一些旧版 Docsify 网站可能使用非版本锁定 URL，如： + +```html +<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> +``` + +如果你的网站使用不含 `@4` 或特定版本号的 URL，请按照以下相同步骤操作。 你需要更新版本说明符和路径结构。 + +## 分步说明 + +### 1. 更新主题 CSS + +**更换主题（v4）：** + +```html +<link + rel="stylesheet" + href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" +/> +<!-- OR if you have non-versioned URL: --> +<link + rel="stylesheet" + href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" +/> +``` + +**使用这个 (v5)：** + +```html +<!-- Core Theme --> +<link + rel="stylesheet" + href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css" +/> +<!-- Optional: Dark Mode Support --> +<link + rel="stylesheet" + href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" + media="(prefers-color-scheme: dark)" +/> +``` + +**注：** 如果你使用的是不同的 v4 主题（buble、dark、pure），v5 核心主题将取代这些主题，不过如果你喜欢，Vue 和 Dark 主题可作为附加组件提供。 + +查看[主题](zh-cn/themes.md) 了解更多详情。 + +### 2. 添加可选的 Body Class（用于设计风格） + +**更新开头的 body tag：** + +```html +<body class="sidebar-chevron-right"></body> +``` + +这将在侧边栏中添加一个 chevron 指示器。 如果你愿意，也可以省略。 + +查看[主题类](zh-cn/themes.md?id=classes) 了解更多详情。 + +### 3. 更新 Docsify 主脚本 + +**修改：** + +```html +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script> +<!-- OR if you have non-versioned URL: --> +<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> +``` + +**为：** + +```html +<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script> +``` + +### 4. 更新插件 URL + +**搜索插件：**\* + +```html +<!-- v4 --> +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script> +<!-- OR non-versioned: --> +<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.js"></script> + +<!-- v5 --> +<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/search.min.js"></script> +``` + +**缩放插件：** + +```html +<!-- v4 --> +<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script> +<!-- OR non-versioned: --> +<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> +``` + +**注意：** 如果你使用其他 Docsify 插件（如 emoji、external-script、front-matter 等），则需要按照相同的模式更新这些 URL： + +- 将 `/lib/plugins/` 改为 `/dist/plugins/` +- 将版本号从 `@4`（或无版本）更新为 `@5` +- 例如：`//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js`变为`//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js` + +## 主要区别摘要 + +- **CDN 路径**：从 `/lib/` 改为 `/dist/` +- **版本**：从 `@4` 更新到 `@5` +- **主题**：v5 使用核心主题（可选附加组件） +- **插件名称**：`zoom-image` → `zoom` + +## 附加说明 + +- 你在 `window.$docsify` 中的配置保持不变 +- 所有 markdown 内容保持不变 +- 对于大多数网站来说，此次升级不会造成中断（但不再支持 Internet Explorer 11 等传统浏览器） +- 为保持与 Docsify v4 相同的视觉风格，可使用 [Vue 主题（附加组件）](zh-cn/themes.md?id=vue-theme-add-on) +- 针对 v4 特定主题类或元素的自定义 CSS 可能需要针对 v5 进行更新 +- v5 核心主题可使用 CSS 变量进行自定义 - 详情请查看[主题自定义](zh-cn/themes.md?id=customization) + +就是这样！ 你的 Docsify 网站现在应该运行在 v5 版本上。