diff --git a/README.md b/README.md index 1882d81..e4333d5 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,32 @@ ## docsify -> 一个神奇的文档网站生成工具 +> 一个神奇的文档网站生成器。 -## 是什么 +## 概述 -docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。 - -这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy.md)。 +docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 `.html` 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 `index.html` 就可以开始编写文档并直接[部署在 GitHub Pages](zh-cn/deploy.md)。 查看[快速开始](zh-cn/quickstart.md)了解详情。 ## 特性 - 无需构建，写完文档直接发布 -- 容易使用并且轻量 (~19kB gzipped) +- 容易使用并且轻量 (压缩后 ~21kB) - 智能的全文搜索 - 提供多套主题 - 丰富的 API - 支持 Emoji -- 兼容 IE10+ -- 支持 SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo)) +- 兼容 IE11 +- 支持服务端渲染 SSR ([示例](https://github.com/docsifyjs/docsify-ssr-demo)) -## 例子 +## 示例 -可以查看 [Showcase](https://github.com/docsifyjs/docsify/#showcase) 来了解使用 docsify 的文档项目。 +可以查看 [Showcase](https://github.com/docsifyjs/docsify/#showcase) 来了解更多在使用 docsify 的文档项目。 ## 捐赠 如果你觉得 docsify 对你有帮助，或者想对我微小的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 -## Community +## 社区 -Users and development team are in the [Gitter](https://gitter.im/docsifyjs/Lobby). +在 [Discord](https://discord.gg/3NwKFyR) 的社区里可以找到 docsify 的用户和开发者团队。 diff --git a/_sidebar.md b/_sidebar.md index 84ab17e..0ddbd62 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -22,7 +22,7 @@ * [CDN](zh-cn/cdn.md) * [离线模式(PWA)](zh-cn/pwa.md) * [服务端渲染 (SSR)](zh-cn/ssr.md) - * [文件嵌入(new)](zh-cn/embed-files.md) + * [文件嵌入](zh-cn/embed-files.md) * [Awesome docsify](zh-cn/awesome.md) * [Changelog](zh-cn/changelog.md) diff --git a/cdn.md b/cdn.md index 5b98d68..53c6c9d 100644 --- a/cdn.md +++ b/cdn.md @@ -1,49 +1,59 @@ # CDN -推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。 +推荐使用 [jsDelivr](//cdn.jsdelivr.net)，能及时获取到最新版。你也可以在[cdn.jsdelivr.net/npm/docsify/](cdn.jsdelivr.net/npm/docsify/)中浏览npm包的源代码。 ## 获取最新版本 -根据 UNPKG 的规则，不指定特定版本号时将引入最新版。 +不指定特定版本号时将引入最新版。 ```html - + - + ``` +也可以使用 [压缩版文件](#compressed-file). + ## 获取指定版本 -如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/` +如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//cdn.jsdelivr.net/npm/docsify@VERSION/` ```html - + - + ``` !> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。 ## 压缩版 -CSS 的压缩文件位于 `/lib/themes/` 目录下 +CSS 的压缩文件位于 `/lib/themes/` 目录下，JS 的压缩文件是原有文件路径的基础上加 `.min` 后缀。 ```html - -``` + + -JS 的压缩文件是原有文件路径的基础上加 `.min`后缀 + + +``` ```html - + + + + + ``` ## 其他 CDN -- http://www.bootcdn.cn/docsify (支持国内) +- https://www.bootcdn.cn/docsify/ (支持国内) - https://cdn.jsdelivr.net/npm/docsify/ (国内外都支持) - https://cdnjs.com/libraries/docsify +- https://unpkg.com/browse/docsify/ + diff --git a/configuration.md b/configuration.md index b92e159..c0acf3e 100644 --- a/configuration.md +++ b/configuration.md @@ -7,8 +7,8 @@ window.$docsify = { repo: 'docsifyjs/docsify', maxLevel: 3, - coverpage: true - } + coverpage: true, + }; ``` @@ -21,7 +21,7 @@ docsify 初始化的挂载元素，可以是一个 CSS 选择器，默认为 `#a ```js window.$docsify = { - el: '#app' + el: '#app', }; ``` @@ -36,7 +36,7 @@ window.$docsify = { window.$docsify = { repo: 'docsifyjs/docsify', // or - repo: 'https://github.com/docsifyjs/docsify/' + repo: 'https://github.com/docsifyjs/docsify/', }; ``` @@ -49,7 +49,7 @@ window.$docsify = { ```js window.$docsify = { - maxLevel: 4 + maxLevel: 4, }; ``` @@ -66,7 +66,7 @@ window.$docsify = { loadNavbar: true, // 加载 nav.md - loadNavbar: 'nav.md' + loadNavbar: 'nav.md', }; ``` @@ -83,7 +83,20 @@ window.$docsify = { loadSidebar: true, // 加载 summary.md - loadSidebar: 'summary.md' + loadSidebar: 'summary.md', +}; +``` + +## hideSidebar + +- 类型 : `Boolean` +- 默认值: `true` + +这个选项用来完全隐藏侧边栏，侧边栏的任何内容都不会被渲染。 + +```js +window.$docsify = { + hideSidebar: true, }; ``` @@ -96,7 +109,7 @@ window.$docsify = { ```js window.$docsify = { - subMaxLevel: 2 + subMaxLevel: 2, }; ``` @@ -109,7 +122,7 @@ window.$docsify = { ```js window.$docsify = { - auto2top: true + auto2top: true, }; ``` @@ -127,7 +140,7 @@ window.$docsify = { // 文档和仓库根目录下的 README.md 内容一致 homepage: - 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md' + 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md', }; ``` @@ -144,9 +157,49 @@ window.$docsify = { // 直接渲染其他域名的文档 basePath: 'https://docsify.js.org/', - // 甚至直接渲染其他仓库 readme + // 甚至直接渲染其他仓库 basePath: - 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/' + 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/', +}; +``` + +## relativePath + +- 类型: `Boolean` +- 默认值: `false` + +如果该选项设为 **true** ，那么链接会使用相对路径。 + +例如，像这样的目录结构： + +```text +. +└── docs + ├── README.md + ├── guide.md + └── zh-cn + ├── README.md + ├── guide.md + └── config + └── example.md +``` + +如果 **启用** 了相对路径，当前链接是 `http://domain.com/zh-cn/README` ，对应的链接会解析为： + +```text +guide.md => http://domain.com/zh-cn/guide +config/example.md => http://domain.com/zh-cn/config/example +../README.md => http://domain.com/README +/README.md => http://domain.com/README +``` + +```js +window.$docsify = { + // 启用相对路径 + relativePath: true, + + // 禁用相对路径（默认值） + relativePath: false, }; ``` @@ -164,26 +217,26 @@ window.$docsify = { // 自定义文件名 coverpage: 'cover.md', - // mutiple covers + // 多个封面页 coverpage: ['/', '/zh-cn/'], - // mutiple covers and custom file name + // 多个封面页，并指定文件名 coverpage: { '/': 'cover.md', - '/zh-cn/': 'cover.md' - } + '/zh-cn/': 'cover.md', + }, }; ``` ## logo -- Type: `String` +- 类型: `String` -Website logo as it appears in the sidebar, you can resize by CSS. +在侧边栏中出现的网站图标，你可以使用`CSS`来更改大小 ```js window.$docsify = { - logo: '/_media/icon.svg' + logo: '/_media/icon.svg', }; ``` @@ -195,7 +248,15 @@ window.$docsify = { ```js window.$docsify = { - name: 'docsify' + name: 'docsify', +}; +``` + +name 项也可以包含自定义 HTML 代码来方便地定制。 + +```js +window.$docsify = { + name: 'docsify', }; ``` @@ -213,8 +274,8 @@ window.$docsify = { // 按照路由切换 nameLink: { '/zh-cn/': '/zh-cn/', - '/': '/' - } + '/': '/', + }, }; ``` @@ -232,15 +293,15 @@ window.$docsify = { renderer: { link: function() { // ... - } - } + }, + }, }, // function markdown: function(marked, renderer) { // ... return marked; - } + }, }; ``` @@ -265,12 +326,12 @@ window.$docsify = { ```js window.$docsify = { alias: { - '/foo/(+*)': '/bar/$1', // supports regexp + '/foo/(.*)': '/bar/$1', // supports regexp '/zh-cn/changelog': '/changelog', '/changelog': 'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG', - '/.*/_sidebar.md': '/_sidebar.md' // See #301 - } + '/.*/_sidebar.md': '/_sidebar.md', // See #301 + }, }; ``` @@ -283,7 +344,7 @@ window.$docsify = { ```js window.$docsify = { loadSidebar: true, - autoHeader: true + autoHeader: true, }; ``` @@ -295,7 +356,7 @@ window.$docsify = { ```js window.$docsify = { - executeScript: true + executeScript: true, }; ``` @@ -311,33 +372,35 @@ window.$docsify = { ## noEmoji -- type: `Boolean` +- 类型: `Boolean` 禁用 emoji 解析。 ```js window.$docsify = { - noEmoji: true + noEmoji: true, }; ``` +?> 如果该选项设为 `false` ，但是你不想解析一些特别的表情符，[参考这里](https://github.com/docsifyjs/docsify/issues/742#issuecomment-586313143) + ## mergeNavbar -- type: `Boolean` +- 类型: `Boolean` 小屏设备下合并导航栏到侧边栏。 ```js window.$docsify = { - mergeNavbar: true + mergeNavbar: true, }; ``` ## formatUpdated -- type: `String|Function` +- 类型: `String|Function` -我们可以显示文档更新日期通过 **{docsify-updated}** 变量. 并且格式化日期通过 `formatUpdated`。参考 https://github.com/lukeed/tinydate#patterns +我们可以通过 **{docsify-updated}** 变量显示文档更新日期. 并且通过 `formatUpdated`配置日期格式。参考 [https://github.com/lukeed/tinydate#patterns](https://github.com/lukeed/tinydate#patterns) ```js window.$docsify = { @@ -347,31 +410,69 @@ window.$docsify = { // ... return time; - } + }, }; ``` ## externalLinkTarget -- type: `String` -- default: `_blank` +- 类型: `String` +- 默认: `_blank` + +外部链接的打开方式。默认为 `_blank` （在新窗口或者标签页中打开） + +```js +window.$docsify = { + externalLinkTarget: '_self', // default: '_blank' +}; +``` + +## cornerExternalLinkTarget + +- 类型:`String` +- 默认值:`_blank` + +右上角链接的打开方式。默认为 `_blank` （在新窗口或者标签页中打开） + +```js +window.$docsify = { + cornerExternalLinkTarget: '_self', // default: '_blank' +}; +``` + +## externalLinkRel + +- 类型: `String` +- 默认值: `noopener` -当前默认为 \_blank, 配置一下就可以： +默认为 `noopener` (no opener) 可以防止新打开的外部页面（当 [externalLinkTarget](#externallinktarget) 设为 `_blank` 时）能够控制我们的页面，没有设为 `_blank` 的话就不需要设置这个选项了。 ```js window.$docsify = { - externalLinkTarget: '_self' // default: '_blank' + externalLinkRel: '', // default: 'noopener' }; ``` ## routerMode -- type: `String` -- default: `hash` +- 类型: `String` +- 默认: `hash` + +```js +window.$docsify = { + routerMode: 'history', // default: 'hash' +}; +``` + +## crossOriginLinks + +- type: `Array` + +当设置了`routerMode:'history'`时，你可能会面临跨域的问题，参见 [#1379](https://github.com/docsifyjs/docsify/issues/1379) 。在 Markdown 内容中，有一个简单的方法可以解决，参见[helpers](zh-cn/helpers.md) 中的跨域链接。 ```js window.$docsify = { - routerMode: 'history' // default: 'hash' + crossOriginLinks: ['https://example.com/cross-origin-link'], }; ``` @@ -383,83 +484,219 @@ window.$docsify = { ```js window.$docsify = { - noCompileLinks: ['/foo', '/bar/.*'] + noCompileLinks: ['/foo', '/bar/.*'], +}; +``` + +## onlyCover + +- 类型: `Boolean` + +只在访问主页时加载封面。 + +```js +window.$docsify = { + onlyCover: false, }; ``` ## requestHeaders -- type: `Object` +- 类型: `Object` 设置请求资源的请求头。 ```js window.$docsify = { requestHeaders: { - 'x-token': 'xxx' - } + 'x-token': 'xxx', + }, +}; +``` + +例如设置缓存 + +```js +window.$docsify = { + requestHeaders: { + 'cache-control': 'max-age=600', + }, }; ``` ## ext -- type: `String` +- 类型: `String` 资源的文件扩展名。 ```js window.$docsify = { - ext: '.md' + ext: '.md', }; ``` ## fallbackLanguages -- type: `Array` +- 类型: `Array` -List of languages that will fallback to the default language when a page is request and didn't exists for the given local. +一个语言列表。在浏览这个列表中的语言的翻译文档时都会在请求到一个对应语言的翻译文档，不存在时显示默认语言的同名文档 Example: -- try to fetch the page of `/de/overview`. If this page exists, it'll be displayed -- then try to fetch the default page `/overview` (depending on the default language). If this page exists, it'll be displayed -- then display 404 page. +- 尝试访问`/de/overview`，如果存在则显示 +- 如果不存在则尝试`/overview`（取决于默认语言），如果存在即显示 +- 如果也不存在，显示404页面 ```js window.$docsify = { - fallbackLanguages: ['fr', 'de'] + fallbackLanguages: ['fr', 'de'], }; ``` ## notFoundPage -- type: `Boolean` | `String` | `Object` +- 类型: `Boolean` | `String` | `Object` -Load the `_404.md` file: +在找不到指定页面时加载`_404.md`: ```js window.$docsify = { - notFoundPage: true + notFoundPage: true, }; ``` -Load the customised path of the 404 page: +加载自定义404页面: ```js window.$docsify = { - notFoundPage: 'my404.md' + notFoundPage: 'my404.md', }; ``` -Load the right 404 page according to the localisation: +加载正确的本地化过的404页面: ```js window.$docsify = { notFoundPage: { '/': '_404.md', - '/de': 'de/_404.md' - } + '/de': 'de/_404.md', + }, +}; +``` + +> 注意: 配置过`fallbackLanguages`这个选项的页面与这个选项`notFoundPage`冲突。 + +## topMargin + +- 类型: `Number` +- 默认值: `0` + +让你的内容页在滚动到指定的锚点时，距离页面顶部有一定空间。当你使用 `固定页头` 布局时这个选项很有用，可以让你的锚点对齐标题栏。 + +```js +window.$docsify = { + topMargin: 90, // default: 0 +}; +``` + +## vueComponents + +- type: `Object` + +创建并注册全局 [Vue组件](https://vuejs.org/v2/guide/components.html) 。组件是以组件名称为键，以包含 Vue 选项的对象为值来指定的。组件`data`对每个实例都是唯一的，并且在用户浏览网站时不会持久。 + +```js +window.$docsify = { + vueComponents: { + 'button-counter': { + template: ` + + `, + data() { + return { + count: 0, + }; + }, + }, + }, +}; +``` + +```markdown + +``` + + + + + +## vueGlobalOptions + +- type: `Object` + +指定 [Vue选项](https://vuejs.org/v2/api/#Options-Data) ，用于未明确使用[vueMounts](#mounting-dom-elements)、[vueComponents](#components)或[markdown脚本](#markdown-script)挂载的 Vue 内容。对全局`data`的更改将持续存在，并在任何使用全局引用的地方得到反映。 + +```js +window.$docsify = { + vueGlobalOptions: { + data() { + return { + count: 0, + }; + }, + }, +}; +``` + +```markdown +

+ + {{ count }} + +

+``` + + +

+ + {{ count }} + +

+ + +## vueMounts + +- type: `Object` + +指定要挂载为 [Vue实例](https://vuejs.org/v2/guide/instance.html) 的 DOM 元素及其相关选项。挂载元素使用 [CSS选择器](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) 作为键，并使用包含 Vue 选项的对象作为其值。每次加载新页面时，Docsify 将挂载主内容区域中第一个匹配的元素。挂载元素`data`对每个实例来说都是唯一的，并且不会在用户浏览网站时持久存在。 + +```js +window.$docsify = { + vueMounts: { + '#counter': { + data() { + return { + count: 0, + }; + }, + }, + }, }; ``` -> Note: The options with fallbackLanguages didn't work with the `notFoundPage` options. +```markdown +
+ + {{ count }} + +
+``` + + + + {{ count }} + + diff --git a/cover.md b/cover.md index 1577cfa..cf4927a 100644 --- a/cover.md +++ b/cover.md @@ -9,41 +9,43 @@ _index.html_ ```html + + - + ``` -_\_coverpage.md_ - ```markdown + + ![logo](_media/icon.svg) -# docsify +# docsify 3.5 -> A magical documentation site generator. +> 一个神奇的文档网站生成器。 -* Simple and lightweight (~12kb gzipped) -* Multiple themes -* Not build static html files +- 简单、轻便 (压缩后 ~21kB) +- 无需生成 html 文件 +- 众多主题 [GitHub](https://github.com/docsifyjs/docsify/) -[Get Started](#quick-start) +[Get Started](#docsify) ``` -!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。 - ## 自定义背景 目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。 -_\_coverpage.md_ +`_coverpage.md` ```markdown -# docsify + + +# docsify 3.5 [GitHub](https://github.com/docsifyjs/docsify/) [Get Started](#quick-start) @@ -87,7 +89,7 @@ window.$docsify = { }; ``` -或者具体指名文件名 +或者指定具体的文件名 ```js window.$docsify = { diff --git a/custom-navbar.md b/custom-navbar.md index 5bb5156..b5438f2 100644 --- a/custom-navbar.md +++ b/custom-navbar.md @@ -1,10 +1,13 @@ # 自定义导航栏 -我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。 +## HTML +如果你需要定制导航栏，可以用 HTML 创建一个导航栏。 -_index.html_ +!> 注意：文档的链接都要以 `#/` 开头。 ```html + +