first commit
This commit is contained in:
qingwei.li
commit
9cb6c2d1e7
|
|
@ -0,0 +1,34 @@
|
|||
## docsify
|
||||
|
||||
> 一个神奇的文档网站生成工具
|
||||
|
||||
## 是什么
|
||||
|
||||
docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。
|
||||
|
||||
这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy.md)。
|
||||
|
||||
查看[快速开始](zh-cn/quickstart.md)了解详情。
|
||||
|
||||
## 特性
|
||||
|
||||
- 无需构建，写完文档直接发布
|
||||
- 容易使用并且轻量 (~19kB gzipped)
|
||||
- 智能的全文搜索
|
||||
- 提供多套主题
|
||||
- 丰富的 API
|
||||
- 支持 Emoji
|
||||
- 兼容 IE10+
|
||||
- 支持 SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo))
|
||||
|
||||
## 例子
|
||||
|
||||
可以查看 [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).
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
* 入门
|
||||
|
||||
* [快速开始](zh-cn/quickstart.md)
|
||||
* [多页文档](zh-cn/more-pages.md)
|
||||
* [定制导航栏](zh-cn/custom-navbar.md)
|
||||
* [封面](zh-cn/cover.md)
|
||||
|
||||
* 定制化
|
||||
|
||||
* [配置项](zh-cn/configuration.md)
|
||||
* [主题](zh-cn/themes.md)
|
||||
* [插件列表](zh-cn/plugins.md)
|
||||
* [开发插件](zh-cn/write-a-plugin.md)
|
||||
* [Markdown 配置](zh-cn/markdown.md)
|
||||
* [代码高亮](zh-cn/language-highlight.md)
|
||||
|
||||
* 指南
|
||||
|
||||
* [部署](zh-cn/deploy.md)
|
||||
* [文档助手](zh-cn/helpers.md)
|
||||
* [兼容 Vue](zh-cn/vue.md)
|
||||
* [CDN](zh-cn/cdn.md)
|
||||
* [离线模式(PWA)](zh-cn/pwa.md)
|
||||
* [服务端渲染 (SSR)](zh-cn/ssr.md)
|
||||
* [文件嵌入<sup style="color:red">(new)<sup>](zh-cn/embed-files.md)
|
||||
|
||||
* [Awesome docsify](zh-cn/awesome.md)
|
||||
* [Changelog](zh-cn/changelog.md)
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# CDN
|
||||
|
||||
推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。
|
||||
|
||||
## 获取最新版本
|
||||
|
||||
根据 UNPKG 的规则，不指定特定版本号时将引入最新版。
|
||||
|
||||
```html
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//unpkg.com/docsify/lib/docsify.js"></script>
|
||||
```
|
||||
|
||||
## 获取指定版本
|
||||
|
||||
如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/`
|
||||
|
||||
```html
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify@2.0.0/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//unpkg.com/docsify@2.0.0/lib/docsify.js"></script>
|
||||
```
|
||||
|
||||
!> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。
|
||||
|
||||
## 压缩版
|
||||
|
||||
CSS 的压缩文件位于 `/lib/themes/` 目录下
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
|
||||
```
|
||||
|
||||
JS 的压缩文件是原有文件路径的基础上加 `.min`后缀
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
## 其他 CDN
|
||||
|
||||
- http://www.bootcdn.cn/docsify (支持国内)
|
||||
- https://cdn.jsdelivr.net/npm/docsify/ (国内外都支持)
|
||||
- https://cdnjs.com/libraries/docsify
|
||||
|
|
@ -0,0 +1,465 @@
|
|||
# 配置项
|
||||
|
||||
你可以配置在 `window.$docsify` 里。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
repo: 'docsifyjs/docsify',
|
||||
maxLevel: 3,
|
||||
coverpage: true
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## 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: 'docsifyjs/docsify',
|
||||
// or
|
||||
repo: 'https://github.com/docsifyjs/docsify/'
|
||||
};
|
||||
```
|
||||
|
||||
## maxLevel
|
||||
|
||||
- 类型：`Number`
|
||||
- 默认值: `6`
|
||||
|
||||
默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
maxLevel: 4
|
||||
};
|
||||
```
|
||||
|
||||
## loadNavbar
|
||||
|
||||
- 类型：`Boolean|String`
|
||||
- 默认值: `false`
|
||||
|
||||
加载自定义导航栏，参考[定制导航栏](zh-cn/custom-navbar.md) 了解用法。设置为 `true` 后会加载 `_navbar.md` 文件，也可以自定义加载的文件名。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
// 加载 _navbar.md
|
||||
loadNavbar: true,
|
||||
|
||||
// 加载 nav.md
|
||||
loadNavbar: 'nav.md'
|
||||
};
|
||||
```
|
||||
|
||||
## loadSidebar
|
||||
|
||||
- 类型：`Boolean|String`
|
||||
- 默认值: `false`
|
||||
|
||||
加载自定义侧边栏，参考[多页文档](zh-cn/more-pages.md)。设置为 `true` 后会加载 `_sidebar.md` 文件，也可以自定义加载的文件名。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
// 加载 _sidebar.md
|
||||
loadSidebar: true,
|
||||
|
||||
// 加载 summary.md
|
||||
loadSidebar: 'summary.md'
|
||||
};
|
||||
```
|
||||
|
||||
## subMaxLevel
|
||||
|
||||
- 类型：`Number`
|
||||
- 默认值: `0`
|
||||
|
||||
自定义侧边栏后默认不会再生成目录，你也可以通过设置生成目录的最大层级开启这个功能。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
subMaxLevel: 2
|
||||
};
|
||||
```
|
||||
|
||||
## 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/docsifyjs/docsify/master/README.md'
|
||||
};
|
||||
```
|
||||
|
||||
## basePath
|
||||
|
||||
- 类型：`String`
|
||||
|
||||
文档加载的根路径，可以是二级路径或者是其他域名的路径。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
basePath: '/path/',
|
||||
|
||||
// 直接渲染其他域名的文档
|
||||
basePath: 'https://docsify.js.org/',
|
||||
|
||||
// 甚至直接渲染其他仓库 readme
|
||||
basePath:
|
||||
'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
|
||||
};
|
||||
```
|
||||
|
||||
## coverpage
|
||||
|
||||
- 类型：`Boolean|String`
|
||||
- 默认值: `false`
|
||||
|
||||
启用[封面页](zh-cn/cover.md)。开启后是加载 `_coverpage.md` 文件，也可以自定义文件名。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
coverpage: true,
|
||||
|
||||
// 自定义文件名
|
||||
coverpage: 'cover.md',
|
||||
|
||||
// mutiple covers
|
||||
coverpage: ['/', '/zh-cn/'],
|
||||
|
||||
// mutiple covers and custom file name
|
||||
coverpage: {
|
||||
'/': 'cover.md',
|
||||
'/zh-cn/': 'cover.md'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## logo
|
||||
|
||||
- Type: `String`
|
||||
|
||||
Website logo as it appears in the sidebar, you can resize by CSS.
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
logo: '/_media/icon.svg'
|
||||
};
|
||||
```
|
||||
|
||||
## name
|
||||
|
||||
- 类型：`String`
|
||||
|
||||
文档标题，会显示在侧边栏顶部。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
name: 'docsify'
|
||||
};
|
||||
```
|
||||
|
||||
## nameLink
|
||||
|
||||
- 类型：`String`
|
||||
- 默认值：`window.location.pathname`
|
||||
|
||||
点击文档标题后跳转的链接地址。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
nameLink: '/',
|
||||
|
||||
// 按照路由切换
|
||||
nameLink: {
|
||||
'/zh-cn/': '/zh-cn/',
|
||||
'/': '/'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## markdown
|
||||
|
||||
- 类型: `Object|Function`
|
||||
|
||||
参考 [Markdown 配置](zh-cn/markdown.md)。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
// object
|
||||
markdown: {
|
||||
smartypants: true,
|
||||
renderer: {
|
||||
link: function() {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// function
|
||||
markdown: function(marked, renderer) {
|
||||
// ...
|
||||
return marked;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## themeColor
|
||||
|
||||
- 类型：`String`
|
||||
|
||||
替换主题色。利用 [CSS3 支持变量](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables)的特性，对于老的浏览器有 polyfill 处理。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
themeColor: '#3F51B5'
|
||||
};
|
||||
```
|
||||
|
||||
## alias
|
||||
|
||||
- 类型：`Object`
|
||||
|
||||
定义路由别名，可以更自由的定义路由规则。 支持正则。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
alias: {
|
||||
'/foo/(+*)': '/bar/$1', // supports regexp
|
||||
'/zh-cn/changelog': '/changelog',
|
||||
'/changelog':
|
||||
'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
|
||||
'/.*/_sidebar.md': '/_sidebar.md' // See #301
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## autoHeader
|
||||
|
||||
- 类型：`Boolean`
|
||||
|
||||
同时设置 `loadSidebar` 和 `autoHeader` 后，可以根据 `_sidebar.md` 的内容自动为每个页面增加标题。[#78](https://github.com/docsifyjs/docsify/issues/78)
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
autoHeader: true
|
||||
};
|
||||
```
|
||||
|
||||
## executeScript
|
||||
|
||||
- 类型：`Boolean`
|
||||
|
||||
执行文档里的 script 标签里的脚本，只执行第一个 script ([demo](zh-cn/themes.md))。 如果 Vue 存在，则自动开启。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
executeScript: true
|
||||
};
|
||||
```
|
||||
|
||||
```markdown
|
||||
## This is test
|
||||
|
||||
<script>
|
||||
console.log(2333)
|
||||
</script>
|
||||
```
|
||||
|
||||
注意如果执行的是一个外链脚本，比如 jsfiddle 的内嵌 demo，请确保引入 [external-script](plugins.md?id=外链脚本-external-script) 插件。
|
||||
|
||||
## noEmoji
|
||||
|
||||
- type: `Boolean`
|
||||
|
||||
禁用 emoji 解析。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
noEmoji: true
|
||||
};
|
||||
```
|
||||
|
||||
## mergeNavbar
|
||||
|
||||
- type: `Boolean`
|
||||
|
||||
小屏设备下合并导航栏到侧边栏。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
mergeNavbar: true
|
||||
};
|
||||
```
|
||||
|
||||
## formatUpdated
|
||||
|
||||
- type: `String|Function`
|
||||
|
||||
我们可以显示文档更新日期通过 **{docsify-updated<span>}</span>** 变量. 并且格式化日期通过 `formatUpdated`。参考 https://github.com/lukeed/tinydate#patterns
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
formatUpdated: '{MM}/{DD} {HH}:{mm}',
|
||||
|
||||
formatUpdated: function(time) {
|
||||
// ...
|
||||
|
||||
return time;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## externalLinkTarget
|
||||
|
||||
- type: `String`
|
||||
- default: `_blank`
|
||||
|
||||
当前默认为 \_blank, 配置一下就可以：
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
externalLinkTarget: '_self' // default: '_blank'
|
||||
};
|
||||
```
|
||||
|
||||
## routerMode
|
||||
|
||||
- type: `String`
|
||||
- default: `history`
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
routerMode: 'history' // default: 'hash'
|
||||
};
|
||||
```
|
||||
|
||||
## noCompileLinks
|
||||
|
||||
- 类型: `Array`
|
||||
|
||||
有时我们不希望 docsify 处理我们的链接。 参考 [#203](https://github.com/docsifyjs/docsify/issues/203)
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
noCompileLinks: ['/foo', '/bar/.*']
|
||||
};
|
||||
```
|
||||
|
||||
## requestHeaders
|
||||
|
||||
- type: `Object`
|
||||
|
||||
设置请求资源的请求头。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
requestHeaders: {
|
||||
'x-token': 'xxx'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## ext
|
||||
|
||||
- type: `String`
|
||||
|
||||
资源的文件扩展名。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
ext: '.md'
|
||||
};
|
||||
```
|
||||
|
||||
## fallbackLanguages
|
||||
|
||||
- type: `Array<string>`
|
||||
|
||||
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.
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
fallbackLanguages: ['fr', 'de']
|
||||
};
|
||||
```
|
||||
|
||||
## notFoundPage
|
||||
|
||||
- type: `Boolean` | `String` | `Object`
|
||||
|
||||
Load the `_404.md` file:
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
notFoundPage: true
|
||||
};
|
||||
```
|
||||
|
||||
Load the customised path of the 404 page:
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
notFoundPage: 'my404.md'
|
||||
};
|
||||
```
|
||||
|
||||
Load the right 404 page according to the localisation:
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
notFoundPage: {
|
||||
'/': '_404.md',
|
||||
'/de': 'de/_404.md'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
> Note: The options with fallbackLanguages didn't work with the `notFoundPage` options.
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
# 封面
|
||||
|
||||
通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见[配置项#coverpage](configuration.md#coverpage)。
|
||||
|
||||
## 基本用法
|
||||
|
||||
封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。渲染效果如本文档。
|
||||
|
||||
_index.html_
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
coverpage: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
_\_coverpage.md_
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
# docsify
|
||||
|
||||
> A magical documentation site generator.
|
||||
|
||||
* Simple and lightweight (~12kb gzipped)
|
||||
* Multiple themes
|
||||
* Not build static html files
|
||||
|
||||
[GitHub](https://github.com/docsifyjs/docsify/)
|
||||
[Get Started](#quick-start)
|
||||
```
|
||||
|
||||
!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。
|
||||
|
||||
## 自定义背景
|
||||
|
||||
目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。
|
||||
|
||||
_\_coverpage.md_
|
||||
|
||||
```markdown
|
||||
# docsify
|
||||
|
||||
[GitHub](https://github.com/docsifyjs/docsify/)
|
||||
[Get Started](#quick-start)
|
||||
|
||||
<!-- 背景图片 -->
|
||||
|
||||
|
||||
|
||||
<!-- 背景色 -->
|
||||
|
||||
|
||||
```
|
||||
|
||||
## 封面作为首页
|
||||
|
||||
通常封面和首页是同时出现的，当然你也是当封面独立出来通过设置[onlyCover 选项](zh-cn/configuration.md#onlycover)。
|
||||
|
||||
## 多个封面
|
||||
|
||||
如果你的文档网站是多语言的，或许你需要设置多个封面。
|
||||
|
||||
例如你的文档目录结构如下
|
||||
|
||||
```text
|
||||
.
|
||||
└── docs
|
||||
├── README.md
|
||||
├── guide.md
|
||||
├── _coverpage.md
|
||||
└── zh-cn
|
||||
├── README.md
|
||||
└── guide.md
|
||||
└── _coverpage.md
|
||||
```
|
||||
|
||||
那么你可以这么配置
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
coverpage: ['/', '/zh-cn/']
|
||||
};
|
||||
```
|
||||
|
||||
或者具体指名文件名
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
coverpage: {
|
||||
'/': 'cover.md',
|
||||
'/zh-cn/': 'cover.md'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
# 自定义导航栏
|
||||
|
||||
我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。
|
||||
|
||||
_index.html_
|
||||
|
||||
```html
|
||||
<body>
|
||||
<nav>
|
||||
<a href="#/">EN</a>
|
||||
<a href="#/zh-cn/">中文</a>
|
||||
</nav>
|
||||
<div id="app"></div>
|
||||
</body>
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#loadNavbar](configuration.md#loadnavbar)。
|
||||
|
||||
_index.html_
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadNavbar: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
_\_navbar.md_
|
||||
|
||||
```markdown
|
||||
* [En](/)
|
||||
* [中文](/zh-cn/)
|
||||
```
|
||||
|
||||
`_navbar.md` 加载逻辑和 `sidebar` 文件一致，从每层目录下获取。例如当前路由为 `/zh-cn/custom-navbar` 那么是从 `/zh-cn/_navbar.md` 获取导航栏。
|
||||
|
||||
## 嵌套
|
||||
|
||||
如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。
|
||||
|
||||
_\_navbar.md_
|
||||
|
||||
```markdown
|
||||
* 基础
|
||||
* [快速开始](zh-cn/quickstart.md)
|
||||
* [多页文档](zh-cn/more-pages.md)
|
||||
* [定制导航栏](zh-cn/custom-navbar.md)
|
||||
* [封面](zh-cn/cover.md)
|
||||
|
||||
* 配置
|
||||
* [配置项](zh-cn/configuration.md)
|
||||
* [主题](zh-cn/themes.md)
|
||||
* [使用插件](zh-cn/plugins.md)
|
||||
* [Markdown 配置](zh-cn/markdown.md)
|
||||
* [代码高亮](zh-cn/language-highlight.md)
|
||||
```
|
||||
|
||||
效果图
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# 部署
|
||||
|
||||
和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
GitHub Pages 支持从三个地方读取文件
|
||||
|
||||
- `docs/` 目录
|
||||
- master 分支
|
||||
- gh-pages 分支
|
||||
|
||||
我们推荐直接将文档放在 `docs/` 目录下，在设置页面开启 **GitHub Pages** 功能并选择 `master branch /docs folder` 选项。
|
||||
|
||||
|
||||
|
||||
!> 可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。
|
||||
|
||||
## GitLab Pages
|
||||
|
||||
如果你正在部署你的主分支, 在 `.gitlab-ci.yml` 中包含以下脚本：
|
||||
|
||||
?> `.public` 的解决方法是这样的，`cp` 不会无限循环的将 `public/` 复制到自身。
|
||||
|
||||
```YAML
|
||||
pages:
|
||||
stage: deploy
|
||||
script:
|
||||
- mkdir .public
|
||||
- cp -r * .public
|
||||
- mv .public public
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- master
|
||||
```
|
||||
|
||||
!> 你可以用 `- cp -r docs/. public` 替换脚本, 如果 `./docs` 是你的 docsify 子文件夹。
|
||||
|
||||
## VPS
|
||||
|
||||
和部署所有静态网站一样，只需将服务器的访问根目录设定为 `index.html` 文件。
|
||||
|
||||
例如 nginx 的配置
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your.domain.com;
|
||||
|
||||
location / {
|
||||
alias /path/to/dir/of/docs;
|
||||
index index.html;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Netlify
|
||||
|
||||
1. Login to your [Netlify](https://www.netlify.com/) account.
|
||||
2. In the [dashboard](https://app.netlify.com/) page, click **New site from Git**.
|
||||
3. Choose a repository where you store your docs, leave the **Build Command** area blank, fill in the Publish directory area with the directory of your `index.html`, for example it should be docs if you populated it at `docs/index.html`.
|
||||
|
||||
### HTML5 router
|
||||
|
||||
When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`, it's pretty simple when you're using Netlify, populate a `\redirects` file in the docs directory and you're all set:
|
||||
|
||||
```sh
|
||||
/* /index.html 200
|
||||
```
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# 文件嵌入
|
||||
|
||||
docsify 4.6 开始支持嵌入任何类型的文件到文档里。你可以将文件当成 `iframe`、`video`、`audio` 或者 `code block`，如果是 Markdown 文件，甚至可以直接插入到当前文档里。
|
||||
|
||||
这是一个嵌入 Markdown 文件的例子。
|
||||
|
||||
```markdown
|
||||
[filename](../_media/example.md ':include')
|
||||
```
|
||||
|
||||
`example.md` 文件的内容将会直接显示在这里
|
||||
|
||||
[filename](../_media/example.md ':include')
|
||||
|
||||
你可以查看 [example.md](../_media/example.md ':ignore') 原始内容对比效果。
|
||||
|
||||
通常情况下，这样的语法将会被当作链接处理。但是在 docsify 里，如果你添加一个 `:include` 选项，它就会被当作文件嵌入。
|
||||
|
||||
## 嵌入的类型
|
||||
|
||||
当前，嵌入的类型是通过文件后缀自动识别的，这是目前支持的类型：
|
||||
|
||||
* **iframe** `.html`, `.htm`
|
||||
* **markdown** `.markdown`, `.md`
|
||||
* **audio** `.mp3`
|
||||
* **video** `.mp4`, `.ogg`
|
||||
* **code** other file extension
|
||||
|
||||
当然，你也可以强制设置嵌入类型。例如你想将 Markdown 文件当作一个 `code block` 嵌入。
|
||||
|
||||
```markdown
|
||||
[filename](../_media/example.md ':include :type=code')
|
||||
```
|
||||
|
||||
你将得到
|
||||
|
||||
[filename](../_media/example.md ':include :type=code')
|
||||
|
||||
## 标签属性
|
||||
|
||||
如果你嵌入文件是一个 `iframe`、`audio` 或者 `video`，你可以给这些标签设置属性。
|
||||
|
||||
```markdown
|
||||
[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')
|
||||
```
|
||||
|
||||
[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')
|
||||
|
||||
看见没？你只需要直接写属性就好了，每个标签有哪些属性建议你查看 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)。
|
||||
|
||||
## 代码块高亮
|
||||
|
||||
如果是嵌入一个代码块，你可以设置高亮的语言，或者让它自动识别。这里是手动设置高亮语言
|
||||
|
||||
```markdown
|
||||
[](../_media/example.html ':include :type=code text')
|
||||
```
|
||||
|
||||
⬇️
|
||||
|
||||
[](../_media/example.html ':include :type=code text')
|
||||
|
||||
?> 如何高亮代码？你可以查看[这份文档](language-highlight.md).
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
# 文档助手
|
||||
|
||||
docsify 扩展了一些 Markdown 语法，可以让文档更易读。
|
||||
|
||||
## 强调内容
|
||||
|
||||
适合显示重要的提示信息，语法为 `!> 内容`。
|
||||
|
||||
```markdown
|
||||
!> 一段重要的内容，可以和其他 **Markdown** 语法混用。
|
||||
```
|
||||
|
||||
!> 一段重要的内容，可以和其他 **Markdown** 语法混用。
|
||||
|
||||
## 普通提示
|
||||
|
||||
普通的提示信息，比如写 TODO 或者参考内容等。
|
||||
|
||||
```markdown
|
||||
?> _TODO_ 完善示例
|
||||
```
|
||||
|
||||
?> _TODO_ 完善示例
|
||||
|
||||
## 忽略编译链接
|
||||
|
||||
有时候我们会把其他一些相对路径放到链接上，你必须告诉 docsify 你不需要编译这个链接。 例如：
|
||||
|
||||
```md
|
||||
[link](/demo/)
|
||||
```
|
||||
|
||||
它将被编译为 `<a href="/#/demo/">link</a>` 并将加载 `/demo/README.md`. 可能你想跳转到 `/demo/index.html`。
|
||||
|
||||
现在你可以做到这一点
|
||||
|
||||
```md
|
||||
[link](/demo/ ':ignore')
|
||||
```
|
||||
|
||||
即将会得到 `<a href="/demo/">link</a>` html 代码。不要担心，你仍然可以为链接设置标题。
|
||||
|
||||
```md
|
||||
[link](/demo/ ':ignore title')
|
||||
|
||||
<a href="/demo/" title="title">link</a>
|
||||
```
|
||||
|
||||
## 设置链接的 target 属性
|
||||
|
||||
```md
|
||||
[link](/demo ':target=_blank')
|
||||
[link](/demo2 ':target=_self')
|
||||
```
|
||||
|
||||
## Github 任务列表
|
||||
|
||||
```md
|
||||
- [ ] foo
|
||||
- bar
|
||||
- [x] baz
|
||||
- [] bam <~ not working
|
||||
- [ ] bim
|
||||
- [ ] lim
|
||||
```
|
||||
|
||||
- [ ] foo
|
||||
- bar
|
||||
- [x] baz
|
||||
- [] bam <~ not working
|
||||
- [ ] bim
|
||||
- [ ] lim
|
||||
|
||||
## Image resizing
|
||||
|
||||
```md
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
# 代码高亮
|
||||
|
||||
内置的代码高亮工具是 [Prism](https://github.com/PrismJS/prism)，默认支持 CSS、JavaScript 和 HTML。如果需要高亮其语言——例如 PHP——可以手动引入代码高亮插件。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
|
||||
<script src="//unpkg.com/prismjs/components/prism-php.js"></script>
|
||||
```
|
||||
|
||||
?> 其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
# Markdown 配置
|
||||
|
||||
内置的 Markdown 解析器是 [marked](https://github.com/markedjs/marked)，可以修改它的配置。同时可以直接配置 `renderer`。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
markdown: {
|
||||
smartypants: true,
|
||||
renderer: {
|
||||
link: function() {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
?> 完整配置参数参考 [marked 文档](https://github.com/markedjs/marked#options-1)
|
||||
|
||||
当然也可以完全定制 Markdown 解析规则。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
markdown: function(marked, renderer) {
|
||||
// ...
|
||||
|
||||
return marked
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 支持 mermaid
|
||||
|
||||
```js
|
||||
// Import mermaid
|
||||
// <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.css">
|
||||
// <script src="//cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
|
||||
mermaid.initialize({ startOnLoad: false });
|
||||
|
||||
window.$docsify = {
|
||||
markdown: {
|
||||
renderer: {
|
||||
code: function(code, lang) {
|
||||
if (lang === "mermaid") {
|
||||
return (
|
||||
'<div class="mermaid">' + mermaid.render(lang, code) + "</div>"
|
||||
);
|
||||
}
|
||||
return this.origin.code.apply(this, arguments);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
# 多页文档
|
||||
|
||||
如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。
|
||||
|
||||
假设你的目录结构如下：
|
||||
|
||||
```text
|
||||
-| docs/
|
||||
-| README.md
|
||||
-| guide.md
|
||||
-| zh-cn/
|
||||
-| README.md
|
||||
-| guide.md
|
||||
```
|
||||
|
||||
那么对应的访问页面将是
|
||||
|
||||
```text
|
||||
docs/README.md => http://domain.com
|
||||
docs/guide.md => http://domain.com/guide
|
||||
docs/zh-cn/README.md => http://domain.com/zh-cn/
|
||||
docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
||||
```
|
||||
|
||||
## 定制侧边栏
|
||||
|
||||
默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。
|
||||
|
||||
首先配置 `loadSidebar` 选项，具体配置规则见[配置项#loadSidebar](zh-cn/configuration.md#loadsidebar)。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
接着创建 `_sidebar.md` 文件，内容如下
|
||||
|
||||
```markdown
|
||||
* [首页](zh-cn/)
|
||||
* [指南](zh-cn/guide)
|
||||
```
|
||||
|
||||
!> 需要在文档根目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。
|
||||
|
||||
`_sidebar.md` 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 `/zh-cn/more-pages` 则从 `/zh-cn/_sidebar.md` 获取文件，如果不存在则从 `/_sidebar.md` 获取。
|
||||
|
||||
当然你也可以配置 `alias` 避免不必要的回退过程。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
alias: {
|
||||
'/.*/_sidebar.md': '/_sidebar.md'
|
||||
}
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## 显示目录
|
||||
|
||||
自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 2
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
## 忽略副标题
|
||||
|
||||
当设置了 `subMaxLevel` 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 `{docsify-ignore}` 。
|
||||
|
||||
```markdown
|
||||
# Getting Started
|
||||
|
||||
## Header {docsify-ignore}
|
||||
|
||||
该标题不会出现在侧边栏的目录中。
|
||||
```
|
||||
|
||||
要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 `{docsify-ignore-all}` 。
|
||||
|
||||
```markdown
|
||||
# Getting Started {docsify-ignore-all}
|
||||
|
||||
## Header
|
||||
|
||||
该标题不会出现在侧边栏的目录中。
|
||||
```
|
||||
|
||||
在使用时， `{docsify-ignore}` 和 `{docsify-ignore-all}` 都不会在页面上呈现。
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
# 插件列表
|
||||
|
||||
## 全文搜索 - Search
|
||||
|
||||
全文搜索插件会根据当前页面上的超链接获取文档内容，在 `localStorage` 内建立文档索引。默认过期时间为一天，当然我们可以自己指定需要缓存的文件列表或者配置过期时间。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
search: 'auto', // 默认值
|
||||
|
||||
search : [
|
||||
'/', // => /README.md
|
||||
'/guide', // => /guide.md
|
||||
'/get-started', // => /get-started.md
|
||||
'/zh-cn/', // => /zh-cn/README.md
|
||||
],
|
||||
|
||||
// 完整配置参数
|
||||
search: {
|
||||
maxAge: 86400000, // 过期时间，单位毫秒，默认一天
|
||||
paths: [], // or 'auto'
|
||||
placeholder: 'Type to search',
|
||||
|
||||
// 支持本地化
|
||||
placeholder: {
|
||||
'/zh-cn/': '搜索',
|
||||
'/': 'Type to search'
|
||||
},
|
||||
|
||||
noData: 'No Results!',
|
||||
|
||||
// 支持本地化
|
||||
noData: {
|
||||
'/zh-cn/': '找不到结果',
|
||||
'/': 'No Results'
|
||||
},
|
||||
|
||||
// 搜索标题的最大程级, 1 - 6
|
||||
depth: 2
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
|
||||
```
|
||||
|
||||
## 谷歌统计 - Google Analytics
|
||||
|
||||
需要配置 track id 才能使用。
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
ga: 'UA-XXXXX-Y'
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/ga.js"></script>
|
||||
```
|
||||
|
||||
也可以通过 `data-ga` 配置 id。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify" data-ga="UA-XXXXX-Y"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/ga.js"></script>
|
||||
```
|
||||
|
||||
## emoji
|
||||
|
||||
默认是提供 emoji 解析的，能将类似 `:100:` 解析成 :100:。但是它不是精准的，因为没有处理非 emoji 的字符串。如果你需要正确解析 emoji 字符串，你可以引入这个插件。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/emoji.js"></script>
|
||||
```
|
||||
|
||||
## 外链脚本 - External Script
|
||||
|
||||
如果文档里的 script 是内联脚本，可以直接执行；而如果是外链脚本（即 js 文件内容由 `src` 属性引入），则需要使用此插件。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/external-script.js"></script>
|
||||
```
|
||||
|
||||
## Demo code with instant preview and jsfiddle integration
|
||||
|
||||
With this plugin, sample code can be rendered on the page instantly, so that the readers can see the preview immediately.
|
||||
When readers expand the demo box, the source code and description are shown there. if they click the button `Try in Jsfiddle`,
|
||||
`jsfiddle.net` will be open with the code of this sample, which allow readers to revise the code and try on their own.
|
||||
|
||||
[Vue](https://njleonzhang.github.io/docsify-demo-box-vue/) and [React](https://njleonzhang.github.io/docsify-demo-box-react/) are both supported.
|
||||
|
||||
## 图片缩放 - Zoom image
|
||||
|
||||
Medium's 风格的图片缩放插件. 基于 [medium-zoom](https://github.com/francoischalifour/medium-zoom)。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
|
||||
```
|
||||
|
||||
忽略某张图片
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
## 在 Github 上编辑
|
||||
|
||||
在每一页上添加 `Edit on github` 按钮. 由第三方库提供, 查看 [document](https://github.com/njleonzhang/docsify-edit-on-github)
|
||||
|
||||
## Copy to Clipboard
|
||||
|
||||
Add a simple `Click to copy` button to all preformatted code blocks to effortlessly allow users to copy example code from your docs. Provided by [@jperasmus](https://github.com/jperasmus)
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify-copy-code"></script>
|
||||
```
|
||||
|
||||
See [here](https://github.com/jperasmus/docsify-copy-code/blob/master/README.md) for more details.
|
||||
|
||||
## Disqus
|
||||
|
||||
Disqus comments. https://disqus.com/
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
disqus: 'shortname'
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/disqus.min.js"></script>
|
||||
```
|
||||
|
||||
## Gitalk
|
||||
|
||||
[Gitalk](https://github.com/gitalk/gitalk) is a modern comment component based on Github Issue and Preact.
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
|
||||
|
||||
<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
|
||||
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
|
||||
<script>
|
||||
const gitalk = new Gitalk({
|
||||
clientID: 'Github Application Client ID',
|
||||
clientSecret: 'Github Application Client Secret',
|
||||
repo: 'Github repo',
|
||||
owner: 'Github repo owner',
|
||||
admin: ['Github repo collaborators, only these guys can initialize github issues'],
|
||||
// facebook-like distraction free mode
|
||||
distractionFreeMode: false
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
Pagination for docsify. By [@imyelo](https://github.com/imyelo)
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
|
||||
```
|
||||
|
||||
## Code Fund
|
||||
|
||||
帮你快速接入[Code Fund](https://codesponsor.io/)的[插件](https://github.com/njleonzhang/docsify-plugin-codefund), 由[@njleonzhang](https://github.com/njleonzhang)提供。
|
||||
|
||||
> Code Fund 以前叫 codesponsor
|
||||
|
||||
```
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
DocsifyCodefund.create('51d43327-eea3-4e27-bd44-e075e67a84fb') // 把这个id改成你的codefund id
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
# 离线模式
|
||||
|
||||
[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)(PWA) 是一项融合 Web 和 Native 应用各项优点的解决方案。我们可以利用其支持离线功能的特点，让我们的网站可以在信号差或者离线状态下正常运行。
|
||||
要使用它也非常容易。
|
||||
|
||||
## 创建 serviceWorker
|
||||
这里已经整理好了一份代码，你只需要在网站根目录下创建一个 `sw.js` 文件，并粘贴下面的代码。
|
||||
|
||||
*sw.js*
|
||||
|
||||
```js
|
||||
/* ===========================================================
|
||||
* docsify sw.js
|
||||
* ===========================================================
|
||||
* Copyright 2016 @huxpro
|
||||
* Licensed under Apache 2.0
|
||||
* Register service worker.
|
||||
* ========================================================== */
|
||||
|
||||
const RUNTIME = 'docsify'
|
||||
const HOSTNAME_WHITELIST = [
|
||||
self.location.hostname,
|
||||
'fonts.gstatic.com',
|
||||
'fonts.googleapis.com',
|
||||
'unpkg.com'
|
||||
]
|
||||
|
||||
// The Util Function to hack URLs of intercepted requests
|
||||
const getFixedUrl = (req) => {
|
||||
var now = Date.now()
|
||||
var url = new URL(req.url)
|
||||
|
||||
// 1. fixed http URL
|
||||
// Just keep syncing with location.protocol
|
||||
// fetch(httpURL) belongs to active mixed content.
|
||||
// And fetch(httpRequest) is not supported yet.
|
||||
url.protocol = self.location.protocol
|
||||
|
||||
// 2. add query for caching-busting.
|
||||
// Github Pages served with Cache-Control: max-age=600
|
||||
// max-age on mutable content is error-prone, with SW life of bugs can even extend.
|
||||
// Until cache mode of Fetch API landed, we have to workaround cache-busting with query string.
|
||||
// Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190
|
||||
if (url.hostname === self.location.hostname) {
|
||||
url.search += (url.search ? '&' : '?') + 'cache-bust=' + now
|
||||
}
|
||||
return url.href
|
||||
}
|
||||
|
||||
/**
|
||||
* @Lifecycle Activate
|
||||
* New one activated when old isnt being used.
|
||||
*
|
||||
* waitUntil(): activating ====> activated
|
||||
*/
|
||||
self.addEventListener('activate', event => {
|
||||
event.waitUntil(self.clients.claim())
|
||||
})
|
||||
|
||||
/**
|
||||
* @Functional Fetch
|
||||
* All network requests are being intercepted here.
|
||||
*
|
||||
* void respondWith(Promise<Response> r)
|
||||
*/
|
||||
self.addEventListener('fetch', event => {
|
||||
// Skip some of cross-origin requests, like those for Google Analytics.
|
||||
if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) {
|
||||
// Stale-while-revalidate
|
||||
// similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale
|
||||
// Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1
|
||||
const cached = caches.match(event.request)
|
||||
const fixedUrl = getFixedUrl(event.request)
|
||||
const fetched = fetch(fixedUrl, { cache: 'no-store' })
|
||||
const fetchedCopy = fetched.then(resp => resp.clone())
|
||||
|
||||
// Call respondWith() with whatever we get first.
|
||||
// If the fetch fails (e.g disconnected), wait for the cache.
|
||||
// If there’s nothing in cache, wait for the fetch.
|
||||
// If neither yields a response, return offline pages.
|
||||
event.respondWith(
|
||||
Promise.race([fetched.catch(_ => cached), cached])
|
||||
.then(resp => resp || fetched)
|
||||
.catch(_ => { /* eat any errors */ })
|
||||
)
|
||||
|
||||
// Update the cache with the version we fetched (only for ok status)
|
||||
event.waitUntil(
|
||||
Promise.all([fetchedCopy, caches.open(RUNTIME)])
|
||||
.then(([response, cache]) => response.ok && cache.put(event.request, response))
|
||||
.catch(_ => { /* eat any errors */ })
|
||||
)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 注册
|
||||
|
||||
现在，到 `index.html` 里注册它。这个功能只能工作在一些现代浏览器上，所以我们需要加个判断。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<script>
|
||||
if (typeof navigator.serviceWorker !== 'undefined') {
|
||||
navigator.serviceWorker.register('sw.js')
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## 体验一下
|
||||
|
||||
发布你的网站，并开始享受离线模式的魔力吧！:ghost: 当然你现在看到的 docsify 的文档网站已经支持离线模式了，你可以关掉 Wi-Fi 体验一下。
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
# 快速开始
|
||||
|
||||
推荐安装 `docsify-cli` 工具，可以方便创建及本地预览文档网站。
|
||||
|
||||
```bash
|
||||
npm i docsify-cli -g
|
||||
```
|
||||
|
||||
## 初始化项目
|
||||
|
||||
如果想在项目的 `./docs` 目录里写文档，直接通过 `init` 初始化项目。
|
||||
|
||||
```bash
|
||||
docsify init ./docs
|
||||
```
|
||||
|
||||
## 开始写文档
|
||||
|
||||
初始化成功后，可以看到 `./docs` 目录下创建的几个文件
|
||||
|
||||
- `index.html` 入口文件
|
||||
- `README.md` 会做为主页内容渲染
|
||||
- `.nojekyll` 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
|
||||
|
||||
直接编辑 `docs/README.md` 就能更新网站内容，当然也可以[写多个页面](zh-cn/more-pages.md)。
|
||||
|
||||
## 本地预览网站
|
||||
|
||||
运行一个本地服务器通过 `docsify serve` 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。
|
||||
|
||||
```bash
|
||||
docsify serve docs
|
||||
```
|
||||
|
||||
?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/docsifyjs/docsify-cli)。
|
||||
|
||||
## 手动初始化
|
||||
|
||||
如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 `index.html` 文件。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<meta charset="UTF-8">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
<script>
|
||||
window.$docsify = {
|
||||
//...
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
如果系统里安装 Python 的话，也可以很轻易的启动一个静态服务器。
|
||||
|
||||
```bash
|
||||
cd docs && python -m SimpleHTTPServer 3000
|
||||
```
|
||||
|
||||
## Loading 提示
|
||||
|
||||
初始化时会显示 `Loading...` 内容，你可以自定义提示信息。
|
||||
|
||||
*index.html*
|
||||
```html
|
||||
<div id="app">加载中</div>
|
||||
```
|
||||
|
||||
如果更改了 `el` 的配置，需要将该元素加上 `data-app` 属性。
|
||||
|
||||
*index.html*
|
||||
```html
|
||||
<div data-app id="main">加载中</div>
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
el: '#main'
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
# 服务端渲染（SSR）
|
||||
|
||||
先看例子 https://docsify.now.sh
|
||||
|
||||
项目地址在 https://github.com/docsifyjs/docsify-ssr-demo
|
||||
|
||||
|
||||
|
||||
文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。
|
||||
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
||||
如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。
|
||||
|
||||
```bash
|
||||
mkdir my-ssr-demo && cd my-ssr-demo
|
||||
npm init -y
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
配置 `package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"start": "docsify start .",
|
||||
"deploy": "now -p"
|
||||
},
|
||||
"docsify": {
|
||||
"config": {
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。其中 `basePath` 为文档所在的路径，可以填你的 docsify 文档网站。
|
||||
|
||||
配置可以单独写在配置文件内，然后通过 `--config config.js` 加载。
|
||||
|
||||
渲染的基础模版也可以自定义，配置在 `template` 属性上，例如
|
||||
|
||||
```js
|
||||
"docsify": {
|
||||
"template": "./ssr.html",
|
||||
"config": {
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*ssr.html*
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>docsify</title>
|
||||
<link rel="icon" href="_media/favicon.ico">
|
||||
<meta name="keywords" content="doc,docs,documentation,gitbook,creator,generator,github,jekyll,github-pages">
|
||||
<meta name="description" content="A magical documentation generator.">
|
||||
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" title="vue">
|
||||
</head>
|
||||
<body>
|
||||
<!--inject-app-->
|
||||
<!--inject-config-->
|
||||
</body>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
||||
</html>
|
||||
|
||||
```
|
||||
|
||||
其中 `<!--inject-app-->` 和 `<!--inject-config-->` 为占位符，会自动将渲染后的 html 和配置内容注入到页面上。
|
||||
|
||||
现在，你可以运行 `npm start` 预览效果，如果没有问题就通过 `npm run deploy` 部署服务。
|
||||
|
||||
```bash
|
||||
npm start
|
||||
# open http://localhost:4000
|
||||
|
||||
npm run deploy
|
||||
# now ...
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 更多玩法
|
||||
|
||||
`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。
|
||||
|
||||
```js
|
||||
var Renderer = require('docsify-server-renderer')
|
||||
var readFileSync = require('fs').readFileSync
|
||||
|
||||
// init
|
||||
var renderer = new Renderer({
|
||||
template: readFileSync('./docs/index.template.html', 'utf-8').,
|
||||
config: {
|
||||
name: 'docsify',
|
||||
repo: 'docsifyjs/docsify'
|
||||
}
|
||||
})
|
||||
|
||||
renderer.renderToString(url)
|
||||
.then(html => {})
|
||||
.catch(err => {})
|
||||
```
|
||||
|
||||
当然文档文件和 server 也是可以部署在一起的，`basePath` 不是一个 URL 的话就会当做文件路径处理，也就是从服务器上加载资源。
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
# 主题
|
||||
|
||||
目前提供三套主题可供选择，模仿 [Vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式。还有 [@liril-net](https://github.com/liril-net) 贡献的黑色风格的主题。
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
|
||||
```
|
||||
|
||||
!> CSS 的压缩文件位于 `/lib/themes/`
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/pure.css">
|
||||
```
|
||||
|
||||
如果你有其他想法或者想开发别的主题，欢迎提 [PR](https://github.com/docsifyjs/docsify/pulls)。
|
||||
|
||||
#### 点击切换主题
|
||||
|
||||
|
||||
<div class="demo-theme-preview">
|
||||
<a data-theme="vue">vue.css</a>
|
||||
<a data-theme="buble">buble.css</a>
|
||||
<a data-theme="dark">dark.css</a>
|
||||
<a data-theme="pure">pure.css</a>
|
||||
</div>
|
||||
|
||||
|
||||
<style>
|
||||
.demo-theme-preview a {
|
||||
padding-right: 10px;
|
||||
}
|
||||
|
||||
.demo-theme-preview a:hover {
|
||||
text-decoration: underline;
|
||||
cursor: pointer;
|
||||
}
|
||||
</style>
|
||||
|
||||
<script>
|
||||
var preview = Docsify.dom.find('.demo-theme-preview');
|
||||
var themes = Docsify.dom.findAll('[rel="stylesheet"]');
|
||||
|
||||
preview.onclick = function (e) {
|
||||
var title = e.target.getAttribute('data-theme')
|
||||
|
||||
themes.forEach(function (theme) {
|
||||
theme.disabled = theme.title !== title
|
||||
});
|
||||
};
|
||||
</script>
|
||||
|
||||
|
||||
## Other themes
|
||||
|
||||
- [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/#/) A delightfully simple theme system for docsify.
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
# 兼容 Vue
|
||||
|
||||
你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。
|
||||
|
||||
|
||||
## 基础用法
|
||||
|
||||
在 `index.html` 里引入 Vue。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/vue"></script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: '#main' })` 创建示例。
|
||||
|
||||
*README.md*
|
||||
|
||||
```markdown
|
||||
# Vue 介绍
|
||||
|
||||
`v-for` 的用法
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li v-for="i in 10">{{ i }}</li>
|
||||
</ul>
|
||||
``
|
||||
|
||||
<ul>
|
||||
<li v-for="i in 10">{{ i }}</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
当然你也可以手动初始化 Vue，这样你可以自定义一些配置。
|
||||
|
||||
*README.md*
|
||||
|
||||
```markdown
|
||||
# Vue 的基本用法
|
||||
|
||||
<div>hello {{ msg }}</div>
|
||||
|
||||
<script>
|
||||
new Vue({
|
||||
el: '#main',
|
||||
data: { msg: 'Vue' }
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
!> 一个 Markdown 文件里只有第一个 `script` 标签内的内容会被执行。
|
||||
|
||||
## 搭配 Vuep 写 Playground
|
||||
|
||||
[Vuep](https://github.com/QingWei-Li/vuep) 是一个提供在线编辑和预览效果的 Vue 组件，搭配 docsify 可以直接在文档里写 Vue 的示例代码，支持 Vue component spec 和 JSX。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<!-- inject css file -->
|
||||
<link rel="stylesheet" href="//unpkg.com/vuep/dist/vuep.css">
|
||||
|
||||
<!-- inject javascript file -->
|
||||
<script src="//unpkg.com/vue"></script>
|
||||
<script src="//unpkg.com/vuep"></script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
|
||||
<!-- or use the compressed files -->
|
||||
<script src="//unpkg.com/vue/dist/vue.min.js"></script>
|
||||
<script src="//unpkg.com/vuep/dist/vuep.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
*README.md*
|
||||
```markdown
|
||||
# Vuep 使用
|
||||
|
||||
<vuep template="#example"></vuep>
|
||||
|
||||
<script v-pre type="text/x-template" id="example">
|
||||
<template>
|
||||
<div>Hello, {{ name }}!</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
module.exports = {
|
||||
data: function () {
|
||||
return { name: 'Vue' }
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</script>
|
||||
```
|
||||
|
||||
<vuep template="#example"></vuep>
|
||||
|
||||
<script v-pre type="text/x-template" id="example">
|
||||
<template>
|
||||
<div>Hello, {{ name }}!</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
module.exports = {
|
||||
data: function () {
|
||||
return { name: 'Vue' }
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</script>
|
||||
|
||||
?> 具体效果参考 [Vuep 文档](https://qingwei-li.github.io/vuep/)。
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
# 自定义插件
|
||||
|
||||
docsify 提供了一套插件机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。
|
||||
|
||||
## 完整功能
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
function (hook, vm) {
|
||||
hook.init(function() {
|
||||
// 初始化时调用，只调用一次，没有参数。
|
||||
})
|
||||
|
||||
hook.beforeEach(function(content) {
|
||||
// 每次开始解析 Markdown 内容时调用
|
||||
// ...
|
||||
return content
|
||||
})
|
||||
|
||||
hook.afterEach(function(html, next) {
|
||||
// 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑
|
||||
// ...
|
||||
// 异步处理完成后调用 next(html) 返回结果
|
||||
next(html)
|
||||
})
|
||||
|
||||
hook.doneEach(function() {
|
||||
// 每次路由切换时数据全部加载完成后调用，没有参数。
|
||||
// ...
|
||||
})
|
||||
|
||||
hook.mounted(function() {
|
||||
// 初始化完成后调用 ，只调用一次，没有参数。
|
||||
})
|
||||
|
||||
hook.ready(function() {
|
||||
// 初始化并第一次加完成数据后调用，没有参数。
|
||||
})
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
!> 如果需要用 docsify 的内部方法，可以通过 `window.Docsify` 获取，通过 `vm` 获取当前实例。
|
||||
|
||||
## 例子
|
||||
|
||||
|
||||
### footer
|
||||
|
||||
给每个页面的末尾加上 `footer`
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
function (hook) {
|
||||
var footer = [
|
||||
'<hr/>',
|
||||
'<footer>',
|
||||
'<span><a href="https://github.com/QingWei-Li">cinwell</a> ©2017.</span>',
|
||||
'<span>Proudly published with <a href="https://github.com/docsifyjs/docsify" target="_blank">docsify</a>.</span>',
|
||||
'</footer>'
|
||||
].join('')
|
||||
|
||||
hook.afterEach(function (html) {
|
||||
return html + footer
|
||||
})
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Edit Button
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
function(hook, vm) {
|
||||
hook.beforeEach(function (html) {
|
||||
var url = 'https://github.com/docsifyjs/docsify/blob/master/docs' + vm.route.file
|
||||
var editHtml = '[📝 EDIT DOCUMENT](' + url + ')\n'
|
||||
|
||||
return editHtml
|
||||
+ html
|
||||
+ '\n----\n'
|
||||
+ 'Last modified {docsify-updated} '
|
||||
+ editHtml
|
||||
})
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue