diff --git a/dev.html b/dev.html index 5fb55eb7..54becd0a 100644 --- a/dev.html +++ b/dev.html @@ -16,8 +16,8 @@ diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index 0d93c1b8..4aa91ca1 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -6,21 +6,22 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件,所有转换工作都是在运行时进行。 -这将非常实用,如果你只是需要快速的写一个小型的文档,或者不想因为生成的一堆 `.html` 文件“污染” commit 记录,只需要创建一个 `index.html` 就可以开始写文档而且直接部署。 +这将非常实用,如果只是需要快速的写一个小型的文档,或者不想因为生成的一堆 `.html` 文件“污染” commit 记录,只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。 可以查看[快速开始](zh-cn/quickstart)一章了解详情。 ## 特性 -- 无需构建,写完 markdown 直接发布 +- 无需构建,写完文档直接发布 - 容易使用并且轻量 (~13Kb gzipped) - 智能的全文检索 - 提供多套主题 - 丰富的 API +- 兼容 IE9+ ## 例子 可以查看 [Showcase](https://github.com/QingWei-Li/docsify/#showcase) 来了解使用 docsify 的文档项目。 -## 支持 +## 捐赠 -有任何使用上的问题或者 Bug 欢迎提 [Issues](https://github.com/QingWei-Li/docsify/issues/),祝你使用愉快! +如果你觉得 docsify 对你有帮助,或者想对我的工作一点资瓷,欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 \ No newline at end of file diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index d2aa0bff..7253e908 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -1,7 +1,7 @@ - 基础 - [快速开始](zh-cn/quickstart) - [多页文档](zh-cn/more-pages) - - [嵌套导航栏](zh-cn/custom-navbar) + - [定制导航栏](zh-cn/custom-navbar) - [封面](zh-cn/cover) - 配置 diff --git a/docs/zh-cn/cdn.md b/docs/zh-cn/cdn.md index 3e776698..f585793b 100644 --- a/docs/zh-cn/cdn.md +++ b/docs/zh-cn/cdn.md @@ -16,14 +16,14 @@ ## 获取指定版本 -如果你担心频繁地版本更新又可能引入未知 Bug,你也可以使用具体的版本。规则是 `//unpkg.com/docsify/VERSION/` +如果担心频繁地版本更新又可能引入未知 Bug,我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/` ```html - + - + ``` !> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。 diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md index 930792ea..9dece41f 100644 --- a/docs/zh-cn/configuration.md +++ b/docs/zh-cn/configuration.md @@ -1,36 +1,244 @@ # 配置项 -> TODO +docsify 有两种配置参数的方式。一种是配置 `window.$docsify` 对象,另一种是给 `script` 标签添加 `data-*` 属性。 + +```html + + + + + +``` + +两种方式可以共存,推荐第一种做法——直接配置 `window.$docsify` 对象——这会让你的配置更加清晰,同时也可以方便的将配置单独写到另一个文件里。 + +!> 通过 `window.$docsify` 配置属性,需要将属性改成驼峰命名法。通过 `data-*` 属性配置,保持短横线的命名规则。 + ## el +- 类型:`String` +- 默认值:`#app` + +docsify 初始化的挂载元素,可以是一个 CSS 选择器,默认为 `#app` 如果不存在就直接绑定在 `body` 上。 + +```js +window.$docsify = { + el: '#app' +} +``` + ## repo +- 类型:`String` +- 默认值: `null` + +配置仓库地址或者 `username/repo` 的字符串,会在页面右上角渲染一个 [GitHub Corner](http://tholman.com/github-corners/) 挂件。 + +```js +window.$docsify = { + repo: 'QingWei-Li/docsify', + // or + repo: 'https://github.com/QingWei-Li/docsify/' +} +``` + + ## max-level +- 类型:`Number` +- 默认值: `6` + +默认情况下会抓取文档中所有标题渲染成目录,可配置最大支持渲染的标题层级。 + + +```js +window.$docsify = { + maxLevel: 4 +} +``` + ## load-navbar +- 类型:`Boolean|String` +- 默认值: `false` + +加载自定义导航栏,参考[定制导航栏](zh-cn/custom-navbar) 了解用法。设置为 `true` 后会加载 `_navbar.md` 文件,也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _navbar.md + loadNavbar: true, + + // 加载 nav.md + loadNavbar: 'nav.md' +} +``` + ## load-sidebar +- 类型:`Boolean|String` +- 默认值: `false` + +加载自定义侧边栏,参考[多页文档](zh-cn/more-pages)。设置为 `true` 后会加载 `_sidebar.md` 文件,也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _sidebar.md + loadSidebar: true, + + // 加载 summary.md + loadSidebar: 'summary.md' +} +``` + ## sub-max-level +- 类型:`Number` +- 默认值: `0` + +自定义侧边栏后默认不会再生成目录,你也可以通过设置生成目录的最大层级开启这个功能, + + +```js +window.$docsify = { + subMaxLevel: 3 +} +``` -## load-navbar ## auto2top +- 类型:`Boolean` +- 默认值: `false` + +切换页面后是否自动跳转到页面顶部。 + +```js +window.$docsify = { + auto2top: true +} +``` + ## homepage +- 类型:`String` +- 默认值: `README.md` + +设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染,或者是文档在仓库根目录的情况使用。 + +```js +window.$docsify = { + // 入口文件改为 /home.md + homepage: 'home.md', + + // 文档和仓库根目录下的 README.md 内容一致 + homepage: 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md' +} +``` ## base-path +- 类型:`String` + +文档加载的根路径,可以是二级路径或者是其他域名的路径。 + +```js +window.$docsify = { + basePath: '/path/', + + // 直接渲染其他域名的文档 + basePath: 'https://docsify.js.org/', + + // 甚至直接渲染其他仓库下的内容 + basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/' +} +``` + + ## coverpage +- 类型:`Boolean|String` +- 默认值: `false` + +启用[封面页](/zh-cn/cover)。开启后是加载 `_coverpage.md` 文件,也可以自定义文件名。 + +```js +window.$docsify = { + coverpage: true, + + // 自定义文件名 + coverpage: 'cover.md' +} +``` + ## name +- 类型:`String` + + +文档标题,会显示在侧边栏顶部。 + +```js +window.$docsify = { + name: 'docsify' +} +``` + ## name-link +- 类型:`String` +- 默认值:`window.location.pathname` + +点击文档标题后跳转的链接地址。 + +```js +window.$docsify = { + nameLink: '/' +} +``` + +## markdown + +- 类型: `Function` + +参考 [Markdown 配置](/zh-cn/markdown)。 + ## theme-color +- 类型:`String` + +替换默认的主题配置。利用 CSS3 支持变量的特性,对于老的浏览器有 polyfill 处理。 + +```js +window.$docsify = { + themeColor: '#3F51B5' +} +``` + ## alias + +定义路由别名,可以更自由的定义路由规则。 + + +```js +window.$docsify = { + alias: { + '/zh-cn/changelog': '/changelog', + '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG' + } +} +``` + diff --git a/docs/zh-cn/cover.md b/docs/zh-cn/cover.md index 8d8da071..cd6a566a 100644 --- a/docs/zh-cn/cover.md +++ b/docs/zh-cn/cover.md @@ -1,3 +1,55 @@ # 封面 -> TODO \ No newline at end of file +一个有封面的文档网站会给用户留下好的印象,通过设置 `coverpage` 参数,可以开启渲染封面的功能。具体用法见见[配置项#coverpage](zh-cn/configuration#coverpage)。 + +## 基本用法 + +封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。 + +```html + + +``` + +*_coverpage.md* + +```markdown +![logo](_media/icon.svg) + +# docsify + +> A magical documentation site generator. + +- Simple and lightweight (~12kb gzipped) +- Multiple themes +- Not build static html files + + +[GitHub](https://github.com/QingWei-Li/docsify/) +[Get Started](#quick-start) +``` + +渲染效果如本文档。 + +!> 一份文档只会在根目录下加载封面,其他页面或者二级目录下都不会加载。 + +## 自定义背景 + +目前的背景是随机生成的渐变色,我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。 + +```markdown +# docsify + +[GitHub](https://github.com/QingWei-Li/docsify/) +[Get Started](#quick-start) + + +![](_media/bg.png) + +![color](#f0f0f0) +``` + diff --git a/docs/zh-cn/custom-navbar.md b/docs/zh-cn/custom-navbar.md index 74bc20a3..4eefeda6 100644 --- a/docs/zh-cn/custom-navbar.md +++ b/docs/zh-cn/custom-navbar.md @@ -1,6 +1,6 @@ # 自定义导航栏 -> TODO +我们可以直接在 HTML 里定义导航栏,要注意链接要以 `#/` 开头。 *index.html* @@ -15,9 +15,10 @@ ``` - ## 配置文件 +如果不想手工写导航栏组件,或者需要根据不同目录加载不同的导航栏,那我们可以通过 Markdown 文件来配置。首先配置 `loadNavbar`,默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#load-navbar](zh-cn/configuration#load-navbar)一节。 + *index.html* @@ -37,8 +38,12 @@ - [中文](/zh-cn/) ``` +`_navbar.md` 加载逻辑和 `sidebar` 文件一致,从每层目录下获取。例如当前路由为 `/zh-cn/custom-navbar` 那么是从 `/zh-cn/_navbar.md` 获取导航栏。 + ## 嵌套 +如果导航内容过多,可以写成嵌套的列表,会被渲染成下拉列表的形式。 + *_navbar.md* @@ -57,4 +62,6 @@ - [代码高亮](zh-cn/language-highlight) ``` +效果图 + ![嵌套导航栏](_images/zh-cn/nested-navbar.png "嵌套导航栏") diff --git a/docs/zh-cn/deploy.md b/docs/zh-cn/deploy.md index 3e33d5e2..2635c562 100644 --- a/docs/zh-cn/deploy.md +++ b/docs/zh-cn/deploy.md @@ -13,7 +13,7 @@ GitHub Pages 支持从三个地方读取文件 ![github pages](_images/deploy-github-pages.png) -!> 你可以将文档放在根目录下,然后选择 **master 分支** 作为文档目录。 +!> 可以将文档放在根目录下,然后选择 **master 分支** 作为文档目录。 ## 部署 VPS diff --git a/docs/zh-cn/helpers.md b/docs/zh-cn/helpers.md index fca6c595..1b1da3c2 100644 --- a/docs/zh-cn/helpers.md +++ b/docs/zh-cn/helpers.md @@ -1,6 +1,6 @@ # 文档助手 -docsify 扩展了一些 Markdown 语法,可以让你的文档更易读。 +docsify 扩展了一些 Markdown 语法,可以让文档更易读。 ## 强调内容 diff --git a/docs/zh-cn/language-highlight.md b/docs/zh-cn/language-highlight.md index bb7029c4..4e5ba47f 100644 --- a/docs/zh-cn/language-highlight.md +++ b/docs/zh-cn/language-highlight.md @@ -1,6 +1,6 @@ # 代码高亮 -内置的代码高亮工具是 [Prism](https://github.com/PrismJS/prism),默认支持 CSS、JavaScript 和 HTML。如果你需要高亮其语言——例如 PHP——你可以手动引入代码高亮插件。 +内置的代码高亮工具是 [Prism](https://github.com/PrismJS/prism),默认支持 CSS、JavaScript 和 HTML。如果需要高亮其语言——例如 PHP——可以手动引入代码高亮插件。 ```html diff --git a/docs/zh-cn/markdown.md b/docs/zh-cn/markdown.md index 51fe044a..579822f1 100644 --- a/docs/zh-cn/markdown.md +++ b/docs/zh-cn/markdown.md @@ -1,6 +1,6 @@ # Markdown 配置 -内置的 Markdown 解析插件是 [marked](https://github.com/chjj/marked),你可以修改它的配置。 +内置的 Markdown 解析插件是 [marked](https://github.com/chjj/marked),可以修改它的配置。 ```js window.$docsify = { @@ -13,7 +13,7 @@ window.$docsify = { ?> 完整配置参数参考 [marked 文档](https://github.com/chjj/marked#options-1) -当然你也可以完全定制 markdown 解析规则。 +当然也可以完全定制 Markdown 解析规则。 ```js window.$docsify = { diff --git a/docs/zh-cn/more-pages.md b/docs/zh-cn/more-pages.md index 0fcbaa6b..5c558e00 100644 --- a/docs/zh-cn/more-pages.md +++ b/docs/zh-cn/more-pages.md @@ -1,6 +1,6 @@ # 多页文档 -如果你的文档需要创建多个页面,或者需要提供多语言的文档。在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件,那么对应的路由就是 `/#/guide`。 +如果需要创建多个页面,或者需要提供多语言的文档。在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件,那么对应的路由就是 `/#/guide`。 一个简单的例子: @@ -24,9 +24,9 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide ## 定制侧边栏 -默认情况下,侧边栏会根据当前文档的目录生成。你可以定制成文档链接,效果如当前的文档的侧边栏。 +默认情况下,侧边栏会根据当前文档的标题生成目录。也可以设置文档链接,通过 Markdown 文件生成,效果如当前的文档的侧边栏。 -首先配置 docsify 的 `loadSidebar` 选项,具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)一章。 +首先配置 docsify 的 `loadSidebar` 选项,具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)一节。 ```html ``` + + diff --git a/docs/zh-cn/plugins.md b/docs/zh-cn/plugins.md index d2098ef3..c230d495 100644 --- a/docs/zh-cn/plugins.md +++ b/docs/zh-cn/plugins.md @@ -4,7 +4,7 @@ ### 全文检索 - Search -全文检索插件会根据当前页面上的超链接获取文档内容,在 `localStorage` 内建立文档索引。默认过期时间为一天,当然你可以自己指定需要缓存的文件列表或者配置过期时间。 +全文检索插件会根据当前页面上的超链接获取文档内容,在 `localStorage` 内建立文档索引。默认过期时间为一天,当然我们可以自己指定需要缓存的文件列表或者配置过期时间。 ```html @@ -45,6 +45,13 @@ ``` +也可以通过 `data-ga` 配置 id。 + +```html + + +``` + ## 自定义插件 docsify 提供了一套插件注册机制,其中提供的钩子(hook)支持处理异步逻辑,可以很方便的扩展功能。 @@ -59,7 +66,7 @@ window.$docsify = { // 初始化时调用,只调用一次 }) hook.beforeEach(function(content) { - // 每次开始解析 markdown 内容时调用 + // 每次开始解析 Markdown 内容时调用 // ... return content }) @@ -77,6 +84,8 @@ window.$docsify = { } ``` +!> 如果需要用 docsify 的内部方法,可以通过 `window.Docsify.utils` 获取。 + #### 例子 给每个页面的末尾加上 `footer` diff --git a/docs/zh-cn/quickstart.md b/docs/zh-cn/quickstart.md index 442c626f..61c84a38 100644 --- a/docs/zh-cn/quickstart.md +++ b/docs/zh-cn/quickstart.md @@ -8,7 +8,7 @@ npm i docsify-cli -g ## 初始化项目 -如果你想在项目的 `./docs` 目录里写文档,直接通过 `init` 初始化项目。 +如果想在项目的 `./docs` 目录里写文档,直接通过 `init` 初始化项目。 ```bash docsify init ./docs @@ -22,7 +22,7 @@ docsify init ./docs - `README.md` 会做为主页内容渲染 - `.nojekyll` 用于阻止 GitHub Pages 会忽略掉下划线开头的文件 -直接编辑 `docs/README.md` 就能更新网站内容,当然你可以[写多个页面](zh-cn/more-pages)。 +直接编辑 `docs/README.md` 就能更新网站内容,当然也可以[写多个页面](zh-cn/more-pages)。 ## 本地预览网站 @@ -36,7 +36,7 @@ docsify serve docs ## 手动初始化 -如果你不喜欢 npm 安装工具,或者不需要本地预览文档功能,我们其实只需要直接创建一个 `index.html` 文件。 +如果不喜欢 npm 安装工具,或者不需要本地预览文档功能,我们其实只需要直接创建一个 `index.html` 文件。 ```html @@ -52,7 +52,7 @@ docsify serve docs ``` -如果你设备里安装 Python 的话,也可以很轻易的启动一个静态服务器。 +如果系统里安装 Python 的话,也可以很轻易的启动一个静态服务器。 ```bash cd docs && python -m SimpleHTTPServer 3000 diff --git a/docs/zh-cn/themes.md b/docs/zh-cn/themes.md index 34ff2e4a..754a0911 100644 --- a/docs/zh-cn/themes.md +++ b/docs/zh-cn/themes.md @@ -1,6 +1,6 @@ # 主题 -目前提供两套主题可供选择,模仿 [vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式。引入其中之一即可。 +目前提供两套主题可供选择,模仿 [vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式,引入其中之一即可。 ```html @@ -9,4 +9,4 @@ !> CSS 的压缩文件位于 `/lib/themes/` -如果你有其他想法或者想开发别的主题,欢迎提 PR。 \ No newline at end of file +如果你有其他想法或者想开发别的主题,欢迎提 [PR](https://github.com/QingWei-Li/docsify/pulls)。 \ No newline at end of file