Update the ALL chinese doc translation to v4.11.3 . (#19)
* Update some translate to 4.11.3 version. * Update more docs to chinese. * update the all document to v4.11.3 chinese. * Update README.md * Update cdn.md * Update configuration.md * Update cover.md * Update custom-navbar.md * Update deploy.md * Update deploy.md * Update embed-files.md * Update plugins.md * PR modify request modified. * delete an extra line. * delete an extra line. * Update deploy.md Co-authored-by: Luffy <52o@qq52o.cn>
This commit is contained in:
Yan Chen
GitHub
parent
ba898769fa
commit
e6a603808c
|
|
@ -13,13 +13,13 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo
|
|||
## 特性
|
||||
|
||||
- 无需构建，写完文档直接发布
|
||||
- 容易使用并且轻量 (~19kB gzipped)
|
||||
- 容易使用并且轻量 (压缩后 ~21kB)
|
||||
- 智能的全文搜索
|
||||
- 提供多套主题
|
||||
- 丰富的 API
|
||||
- 支持 Emoji
|
||||
- 兼容 IE10+
|
||||
- 支持 SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo))
|
||||
- 兼容 IE11
|
||||
- 支持服务端渲染 SSR ([示例](https://github.com/docsifyjs/docsify-ssr-demo))
|
||||
|
||||
## 例子
|
||||
|
||||
|
|
|
|||
33
cdn.md
33
cdn.md
|
|
@ -1,45 +1,53 @@
|
|||
# CDN
|
||||
|
||||
推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。
|
||||
推荐使用 [jsDelivr](//cdn.jsdelivr.net)，能及时获取到最新版。你也可以在[cdn.jsdelivr.net/npm/docsify/](cdn.jsdelivr.net/npm/docsify/)中浏览npm包的源代码。
|
||||
|
||||
## 获取最新版本
|
||||
|
||||
根据 UNPKG 的规则，不指定特定版本号时将引入最新版。
|
||||
不指定特定版本号时将引入最新版。
|
||||
|
||||
```html
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//unpkg.com/docsify/lib/docsify.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.js"></script>
|
||||
```
|
||||
|
||||
也可以使用 [压缩版文件](#compressed-file).
|
||||
|
||||
## 获取指定版本
|
||||
|
||||
如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/`
|
||||
如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//cdn.jsdelivr.net/npm/docsify@VERSION/`
|
||||
|
||||
```html
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify@2.0.0/themes/vue.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.10.2/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//unpkg.com/docsify@2.0.0/lib/docsify.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/docsify.js"></script>
|
||||
```
|
||||
|
||||
!> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。
|
||||
|
||||
## 压缩版
|
||||
|
||||
CSS 的压缩文件位于 `/lib/themes/` 目录下
|
||||
CSS 的压缩文件位于 `/lib/themes/` 目录下，JS 的压缩文件是原有文件路径的基础上加 `.min` 后缀。
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
JS 的压缩文件是原有文件路径的基础上加 `.min`后缀
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<!-- 引入 css -->
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/themes/vue.css">
|
||||
|
||||
<!-- 引入 script -->
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
## 其他 CDN
|
||||
|
|
@ -47,3 +55,4 @@ JS 的压缩文件是原有文件路径的基础上加 `.min`后缀
|
|||
- http://www.bootcdn.cn/docsify (支持国内)
|
||||
- https://cdn.jsdelivr.net/npm/docsify/ (国内外都支持)
|
||||
- https://cdnjs.com/libraries/docsify
|
||||
|
||||
|
|
|
|||
210
configuration.md
210
configuration.md
|
|
@ -7,8 +7,8 @@
|
|||
window.$docsify = {
|
||||
repo: 'docsifyjs/docsify',
|
||||
maxLevel: 3,
|
||||
coverpage: true
|
||||
}
|
||||
coverpage: true,
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
|
|
@ -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,14 +217,14 @@ 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',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -183,7 +236,7 @@ window.$docsify = {
|
|||
|
||||
```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: '<span>docsify</span>',
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -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;
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -269,8 +330,8 @@ window.$docsify = {
|
|||
'/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,
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -317,10 +378,12 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
noEmoji: true
|
||||
noEmoji: true,
|
||||
};
|
||||
```
|
||||
|
||||
?> 如果该选项设为 `false` ，但是你不想解析一些特别的表情符，[参考这里](https://github.com/docsifyjs/docsify/issues/742#issuecomment-586313143)
|
||||
|
||||
## mergeNavbar
|
||||
|
||||
- 类型: `Boolean`
|
||||
|
|
@ -329,7 +392,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
mergeNavbar: true
|
||||
mergeNavbar: true,
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -337,7 +400,7 @@ window.$docsify = {
|
|||
|
||||
- 类型: `String|Function`
|
||||
|
||||
我们可以通过 **{docsify-updated<span>}</span>** 变量显示文档更新日期. 并且通过 `formatUpdated`配置日期格式。参考 https://github.com/lukeed/tinydate#patterns
|
||||
我们可以通过 **{docsify-updated<span>}</span>** 变量显示文档更新日期. 并且通过 `formatUpdated`配置日期格式。参考 [https://github.com/lukeed/tinydate#patterns](https://github.com/lukeed/tinydate#patterns)
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
|
|
@ -347,7 +410,7 @@ window.$docsify = {
|
|||
// ...
|
||||
|
||||
return time;
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -356,11 +419,37 @@ window.$docsify = {
|
|||
- 类型: `String`
|
||||
- 默认: `_blank`
|
||||
|
||||
当前默认为 \_blank, 配置一下就可以：
|
||||
外部链接的打开方式。默认为 `_blank` （在新窗口或者标签页中打开）
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
externalLinkTarget: '_self' // default: '_blank'
|
||||
externalLinkTarget: '_self', // default: '_blank'
|
||||
};
|
||||
```
|
||||
|
||||
## cornerExternalLinkTarget
|
||||
|
||||
- 类型:`String`
|
||||
- 默认值:`_blank`
|
||||
|
||||
右上角链接的打开方式。默认为 `_blank` （在新窗口或者标签页中打开）
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
cornerExternalLinkTarget: '_self', // default: '_blank'
|
||||
};
|
||||
```
|
||||
|
||||
## externalLinkRel
|
||||
|
||||
- 类型: `String`
|
||||
- 默认值: `noopener`
|
||||
|
||||
默认为 `noopener` (no opener) 可以防止新打开的外部页面（当 [externalLinkTarget](#externallinktarget) 设为 `_blank` 时）能够控制我们的页面，没有设为 `_blank` 的话就不需要设置这个选项了。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
externalLinkRel: '', // default: 'noopener'
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -371,7 +460,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
routerMode: 'history' // default: 'hash'
|
||||
routerMode: 'history', // default: 'hash'
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -383,7 +472,19 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
noCompileLinks: ['/foo', '/bar/.*']
|
||||
noCompileLinks: ['/foo', '/bar/.*'],
|
||||
};
|
||||
```
|
||||
|
||||
## onlyCover
|
||||
|
||||
- 类型: `Boolean`
|
||||
|
||||
只在访问主页时加载封面。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
onlyCover: false,
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -396,8 +497,18 @@ window.$docsify = {
|
|||
```js
|
||||
window.$docsify = {
|
||||
requestHeaders: {
|
||||
'x-token': 'xxx'
|
||||
}
|
||||
'x-token': 'xxx',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
例如设置缓存
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
requestHeaders: {
|
||||
'cache-control': 'max-age=600',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -409,7 +520,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
ext: '.md'
|
||||
ext: '.md',
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -427,7 +538,7 @@ Example:
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
fallbackLanguages: ['fr', 'de']
|
||||
fallbackLanguages: ['fr', 'de'],
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -439,7 +550,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
notFoundPage: true
|
||||
notFoundPage: true,
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -447,7 +558,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
notFoundPage: 'my404.md'
|
||||
notFoundPage: 'my404.md',
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -457,9 +568,22 @@ window.$docsify = {
|
|||
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
|
||||
};
|
||||
```
|
||||
|
|
|
|||
24
cover.md
24
cover.md
|
|
@ -9,29 +9,31 @@
|
|||
_index.html_
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
coverpage: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
`_coverpage.md`
|
||||
|
||||
```markdown
|
||||
<!-- _coverpage.md -->
|
||||
|
||||
|
||||
|
||||
# docsify
|
||||
# docsify <small>3.5</small>
|
||||
|
||||
> 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)
|
||||
```
|
||||
|
||||
## 自定义背景
|
||||
|
|
@ -41,7 +43,9 @@ _index.html_
|
|||
`_coverpage.md`
|
||||
|
||||
```markdown
|
||||
# docsify
|
||||
<!-- _coverpage.md -->
|
||||
|
||||
# docsify <small>3.5</small>
|
||||
|
||||
[GitHub](https://github.com/docsifyjs/docsify/)
|
||||
[Get Started](#quick-start)
|
||||
|
|
|
|||
|
|
@ -1,10 +1,13 @@
|
|||
# 自定义导航栏
|
||||
|
||||
我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。
|
||||
## HTML
|
||||
如果你需要定制导航栏，可以用 HTML 创建一个导航栏。
|
||||
|
||||
_index.html_
|
||||
!> 注意：文档的链接都要以 `#/` 开头。
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<body>
|
||||
<nav>
|
||||
<a href="#/">EN</a>
|
||||
|
|
@ -18,38 +21,46 @@ _index.html_
|
|||
|
||||
那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#loadNavbar](configuration.md#loadnavbar)。
|
||||
|
||||
_index.html_
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadNavbar: true
|
||||
}
|
||||
</script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
_\_navbar.md_
|
||||
|
||||
```markdown
|
||||
<!-- _navbar.md -->
|
||||
|
||||
* [En](/)
|
||||
* [中文](/zh-cn/)
|
||||
```
|
||||
|
||||
!> 你需要在 `./docs` 目录下创建一个 `.nojekyll` 文件，以防止 GitHub Pages 忽略下划线开头的文件。
|
||||
|
||||
`_navbar.md` 加载逻辑和 `sidebar` 文件一致，从每层目录下获取。例如当前路由为 `/zh-cn/custom-navbar` 那么是从 `/zh-cn/_navbar.md` 获取导航栏。
|
||||
|
||||
## 嵌套
|
||||
|
||||
如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。
|
||||
|
||||
_navbar.md_
|
||||
|
||||
```markdown
|
||||
|
||||
<!-- _navbar.md -->
|
||||
|
||||
* 入门
|
||||
|
||||
* [快速开始](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)
|
||||
|
|
@ -61,3 +72,28 @@ _navbar.md_
|
|||
效果图
|
||||
|
||||
|
||||
|
||||
## 整合自定义导航栏与 emoji 插件
|
||||
|
||||
如果你使用 [emoji 插件](plugins#emoji):
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
// ...
|
||||
}
|
||||
</script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
|
||||
```
|
||||
|
||||
例如，你可以在自定义导航栏 Markdown 文件中使用旗帜表情：
|
||||
|
||||
```markdown
|
||||
<!-- _navbar.md -->
|
||||
|
||||
* [:us:, :uk:](/)
|
||||
* [:cn:](/zh-cn/)
|
||||
```
|
||||
|
|
|
|||
72
deploy.md
72
deploy.md
|
|
@ -14,7 +14,7 @@ GitHub Pages 支持从三个地方读取文件
|
|||
|
||||
|
||||
|
||||
!> 可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。
|
||||
!> 可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。你需要在部署位置下放一个 `.nojekyll` 文件（比如 `/docs` 目录或者 gh-pages 分支）
|
||||
|
||||
## GitLab Pages
|
||||
|
||||
|
|
@ -38,6 +38,25 @@ pages:
|
|||
|
||||
!> 你可以用 `- cp -r docs/. public` 替换脚本, 如果 `./docs` 是你的 docsify 子文件夹。
|
||||
|
||||
## Firebase 主机
|
||||
|
||||
!> 你需要先使用谷歌账号登陆 [Firebase 控制台](https://console.firebase.google.com) ，然后使用 `npm i -g firebase-tools` 命令安装 Firebase CLI 。
|
||||
|
||||
使用命令行浏览到你的 Firebase 项目目录，大致是 `~/Projects/Docs` 等等。在这里执行 `firebase init` 命令，从菜单中选择 `Hosting` （使用 **空格键** 选择， **方向键** 切换选项， **回车键** 确认。遵照安装说明。
|
||||
|
||||
然后你会有个 `firebase.json` 文件，内容大致如下（我把部署目录从 `public` 改为 `site` 了）：
|
||||
|
||||
```json
|
||||
{
|
||||
"hosting": {
|
||||
"public": "site",
|
||||
"ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
完成后，执行 `docsify init ./site` 构建起始模板（将`site`替换为你在运行`firebase init`时确定的部署目录 - 默认情况下为`public`）。 添加/编辑文档，然后在项目根目录执行 `firebase deploy`。
|
||||
|
||||
## VPS
|
||||
|
||||
和部署所有静态网站一样，只需将服务器的访问根目录设定为 `index.html` 文件。
|
||||
|
|
@ -50,7 +69,7 @@ server {
|
|||
server_name your.domain.com;
|
||||
|
||||
location / {
|
||||
alias /path/to/dir/of/docs;
|
||||
alias /path/to/dir/of/docs/;
|
||||
index index.html;
|
||||
}
|
||||
}
|
||||
|
|
@ -62,10 +81,57 @@ server {
|
|||
2. 在[dashboard](https://app.netlify.com/)页上点击 **New site from Git**.
|
||||
3. 选择那个你用来存储文档的git仓库，将 **Build Command** 留空, 将 **Publish directory** 区域填入你的`index.html`所在的目录，例如：填入`docs`(如果你的`index.html`的相对路径是`docs/index.html`的话).
|
||||
|
||||
### HTML5 router
|
||||
### HTML5 路由
|
||||
|
||||
当使用HTML5路由时，你需要设置一条将所有请求重定向到你的`index.html`的重定向规则。当你使用Netlify时这相当简单，在你的**Publish Directory**下创建一个`\redirects`文件，写进以下内容，然后——:tada:就好了：
|
||||
|
||||
```sh
|
||||
/* /index.html 200
|
||||
```
|
||||
|
||||
## ZEIT Now
|
||||
|
||||
1. 安装 [Now CLI](https://zeit.co/download) ： `npm i -g now`
|
||||
2. 切换到你的 docsify 网站的文档目录，比方说 `cd docs`
|
||||
3. 用一个指令来部署： `now`
|
||||
|
||||
## AWS Amplify
|
||||
|
||||
1. 在 Docsify 项目的 `index.html` 中设置 routerMode 为 *history* 模式：
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
routerMode: 'history'
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
2. 登录到你的 [AWS 控制台](https://aws.amazon.com)。
|
||||
3. 到 [AWS Amplify 仪表盘](https://aws.amazon.com/amplify)。
|
||||
4. 选择 **Deploy** 路线来设置你的项目。
|
||||
5. 若有提示，如果你希望在项目根目录下保存你的文档，保持构建设置为空；如果你想保存文档到其它目录，修改 amplify.yml ：
|
||||
|
||||
```yml
|
||||
version: 0.1
|
||||
frontend:
|
||||
phases:
|
||||
build:
|
||||
commands:
|
||||
- echo "Nothing to build"
|
||||
artifacts:
|
||||
baseDirectory: /docs
|
||||
files:
|
||||
- '**/*'
|
||||
cache:
|
||||
paths: []
|
||||
```
|
||||
|
||||
6. 依次添加如下跳转规则。注意第二条的 PNG 是图片格式，如果你要使用其它图片格式，可以相应修改。
|
||||
|
||||
| Source address | Target address | Type |
|
||||
|----------------|----------------|---------------|
|
||||
| /<*>.md | /<*>.md | 200 (Rewrite) |
|
||||
| /<*>.png | /<*>.png | 200 (Rewrite) |
|
||||
| /<*> | /index.html | 200 (Rewrite) |
|
||||
|
|
|
|||
|
|
@ -27,15 +27,28 @@ docsify 4.6 开始支持嵌入任何类型的文件到文档里。你可以将
|
|||
* **code** other file extension
|
||||
|
||||
当然，你也可以强制设置嵌入类型。例如你想将 Markdown 文件当作一个 `code block` 嵌入。
|
||||
|
||||
```markdown
|
||||
[filename](../_media/example.md ':include :type=code')
|
||||
```
|
||||
|
||||
你将得到
|
||||
你会看到：
|
||||
|
||||
[filename](../_media/example.md ':include :type=code')
|
||||
|
||||
## 嵌入代码片段
|
||||
有时候你并不想嵌入整个文件，可能你只想要其中的几行代码，但你还要在 CI 系统中编译和测试该文件。
|
||||
|
||||
```markdown
|
||||
[filename](../_media/example.js ':include :type=code :fragment=demo')
|
||||
```
|
||||
|
||||
在你的代码文件中，你需要用斜线 `/// [demo]` 包裹该片段（片段的前后都要有）。
|
||||
你也可以使用 `### [demo]` 来包裹。
|
||||
|
||||
示例：
|
||||
|
||||
[filename](../_media/example.js ':include :type=code :fragment=demo')
|
||||
|
||||
## 标签属性
|
||||
|
||||
如果你嵌入文件是一个 `iframe`、`audio` 或者 `video`，你可以给这些标签设置属性。
|
||||
|
|
|
|||
69
helpers.md
69
helpers.md
|
|
@ -53,6 +53,12 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。
|
|||
[link](/demo2 ':target=_self')
|
||||
```
|
||||
|
||||
## 禁用链接
|
||||
|
||||
```md
|
||||
[link](/demo ':disabled')
|
||||
```
|
||||
|
||||
## Github 任务列表
|
||||
|
||||
```md
|
||||
|
|
@ -71,18 +77,79 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。
|
|||
- [ ] bim
|
||||
- [ ] lim
|
||||
|
||||
## 图片缩放
|
||||
## 图片处理
|
||||
|
||||
### 缩放
|
||||
|
||||
```md
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- 支持按百分比缩放 -->
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 设置图片的 Class
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
### 设置图片的 ID
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
## 设置标题的 id 属性
|
||||
|
||||
```md
|
||||
### 你好，世界！ :id=hello-world
|
||||
```
|
||||
|
||||
## html 标签中的 Markdown
|
||||
|
||||
你需要在 html 和 Markdown 内容中插入空行。
|
||||
当你需要在 details 元素中渲染 Markdown 时很有用。
|
||||
|
||||
```markdown
|
||||
<details>
|
||||
<summary>自我评价（点击展开）</summary>
|
||||
|
||||
- Abc
|
||||
- Abc
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>自我评价（点击展开）</summary>
|
||||
|
||||
- Abc
|
||||
- Abc
|
||||
|
||||
</details>
|
||||
|
||||
Markdown 内容也可以被 html 标签包裹。
|
||||
|
||||
```markdown
|
||||
<div style='color: red'>
|
||||
|
||||
- listitem
|
||||
- listitem
|
||||
- listitem
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
<div style='color: red'>
|
||||
|
||||
- Abc
|
||||
- Abc
|
||||
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@
|
|||
内置的代码高亮工具是 [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>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-php.min.js"></script>
|
||||
```
|
||||
|
||||
?> 其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。
|
||||
|
|
|
|||
|
|
@ -37,6 +37,7 @@ window.$docsify = {
|
|||
// <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>
|
||||
|
||||
var num = 0;
|
||||
mermaid.initialize({ startOnLoad: false });
|
||||
|
||||
window.$docsify = {
|
||||
|
|
@ -45,7 +46,7 @@ window.$docsify = {
|
|||
code: function(code, lang) {
|
||||
if (lang === "mermaid") {
|
||||
return (
|
||||
'<div class="mermaid">' + mermaid.render(lang, code) + "</div>"
|
||||
'<div class="mermaid">' + mermaid.render('mermaid-svg-' + num++, code) + "</div>"
|
||||
);
|
||||
}
|
||||
return this.origin.code.apply(this, arguments);
|
||||
|
|
|
|||
|
|
@ -5,12 +5,13 @@
|
|||
假设你的目录结构如下：
|
||||
|
||||
```text
|
||||
-| docs/
|
||||
-| README.md
|
||||
-| guide.md
|
||||
-| zh-cn/
|
||||
-| README.md
|
||||
-| guide.md
|
||||
.
|
||||
└── docs
|
||||
├── README.md
|
||||
├── guide.md
|
||||
└── zh-cn
|
||||
├── README.md
|
||||
└── guide.md
|
||||
```
|
||||
|
||||
那么对应的访问页面将是
|
||||
|
|
@ -29,22 +30,31 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
|||
首先配置 `loadSidebar` 选项，具体配置规则见[配置项#loadSidebar](zh-cn/configuration.md#loadsidebar)。
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
接着创建 `_sidebar.md` 文件，内容如下
|
||||
|
||||
```markdown
|
||||
<!-- docs/_sidebar.md -->
|
||||
|
||||
* [首页](zh-cn/)
|
||||
* [指南](zh-cn/guide)
|
||||
```
|
||||
|
||||
!> 需要在文档根目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。
|
||||
需要在 `./docs` 目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。
|
||||
|
||||
## 嵌套的侧边栏
|
||||
|
||||
你可能想要浏览到一个目录时，只显示这个目录自己的侧边栏，这可以通过在每个文件夹中添加一个 `_sidebar.md` 文件来实现。
|
||||
|
||||
|
||||
`_sidebar.md` 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 `/zh-cn/more-pages` 则从 `/zh-cn/_sidebar.md` 获取文件，如果不存在则从 `/_sidebar.md` 获取。
|
||||
|
||||
|
|
@ -61,18 +71,32 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
|||
</script>
|
||||
```
|
||||
|
||||
!> 你可以在一个子目录中创建一个 `README.md` 文件来作为路由的默认网页。
|
||||
|
||||
## 用侧边栏中选定的条目名称作为页面标题
|
||||
|
||||
一个页面的 `title` 标签是由侧边栏中选中条目的名称所生成的。为了更好的 SEO ，你可以在文件名后面指定页面标题。
|
||||
|
||||
```markdown
|
||||
<!-- docs/_sidebar.md -->
|
||||
* [Home](/)
|
||||
* [Guide](guide.md "The greatest guide in the world")
|
||||
```
|
||||
|
||||
## 显示目录
|
||||
|
||||
自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 2
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
## 忽略副标题
|
||||
|
|
@ -90,9 +114,9 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
|||
要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 `{docsify-ignore-all}` 。
|
||||
|
||||
```markdown
|
||||
# Getting Started {docsify-ignore-all}
|
||||
# 入门 {docsify-ignore-all}
|
||||
|
||||
## Header
|
||||
## 标题
|
||||
|
||||
该标题不会出现在侧边栏的目录中。
|
||||
```
|
||||
|
|
|
|||
64
plugins.md
64
plugins.md
|
|
@ -37,12 +37,12 @@
|
|||
},
|
||||
|
||||
// 搜索标题的最大层级, 1 - 6
|
||||
depth: 2
|
||||
depth: 2,
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
|
||||
```
|
||||
|
||||
## 谷歌统计 - Google Analytics
|
||||
|
|
@ -55,15 +55,15 @@
|
|||
ga: 'UA-XXXXX-Y'
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/ga.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.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>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-XXXXX-Y"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
|
||||
```
|
||||
|
||||
## emoji
|
||||
|
|
@ -71,7 +71,7 @@
|
|||
默认是提供 emoji 解析的，能将类似 `:100:` 解析成 :100:。但是它不是精准的，因为没有处理非 emoji 的字符串。如果你需要正确解析 emoji 字符串，你可以引入这个插件。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/emoji.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
|
||||
```
|
||||
|
||||
## 外链脚本 - External Script
|
||||
|
|
@ -79,42 +79,42 @@
|
|||
如果文档里的 script 是内联脚本，可以直接执行；而如果是外链脚本（即 js 文件内容由 `src` 属性引入），则需要使用此插件。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/external-script.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
|
||||
```
|
||||
|
||||
## Demo code with instant preview and jsfiddle integration
|
||||
|
||||
使用这个插件，示例代码可以在页面上立刻渲染，这样就可以立刻看到效果。当示例框被展开时，源码和描述会被显示出来，如果他们点击`Try in Jsfiddle`这个按钮，将会在`jsfiddle.net`中打开一个包含这些示例代码的项目，这样就可以修改源码和测试了。
|
||||
|
||||
docsify同时支持[Vue](https://njleonzhang.github.io/docsify-demo-box-vue/)和[React](https://njleonzhang.github.io/docsify-demo-box-react/)版本的插件。
|
||||
|
||||
## 图片缩放 - Zoom image
|
||||
|
||||
Medium's 风格的图片缩放插件. 基于 [medium-zoom](https://github.com/francoischalifour/medium-zoom)。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
|
||||
```
|
||||
|
||||
忽略某张图片
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
## 在 Github 上编辑
|
||||
|
||||
在每一页上添加 `Edit on github` 按钮. 由第三方库提供, 查看 [document](https://github.com/njleonzhang/docsify-edit-on-github)
|
||||
|
||||
## 代码即时预览和 jsfiddle 集成
|
||||
|
||||
通过这个插件，示例代码可以在页面上即时呈现，让读者可以立即看到预览。当读者展开演示框时，源码和说明就会显示在那里，如果点击`Try in Jsfiddle`按钮，`jsfiddle.net`就会打开这个例子的代码，让读者自己修改代码和测试。
|
||||
|
||||
docsify同时支持[Vue](https://njleonzhang.github.io/docsify-demo-box-vue/)和[React](https://njleonzhang.github.io/docsify-demo-box-react/)版本的插件。
|
||||
|
||||
## 复制到剪贴板
|
||||
|
||||
在所有的代码块上添加一个简单的`Click to copy`按钮来允许用户从你的文档中轻易地复制代码。由[@jperasmus](https://github.com/jperasmus)提供。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/docsify-copy-code"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
|
||||
```
|
||||
|
||||
从[这里](https://github.com/jperasmus/docsify-copy-code#readme)获取更多信息。
|
||||
详情可参考 [README.md](https://github.com/jperasmus/docsify-copy-code/blob/master/README.md) 。
|
||||
|
||||
## Disqus
|
||||
|
||||
|
|
@ -126,7 +126,7 @@ Disqus评论系统支持。 https://disqus.com/
|
|||
disqus: 'shortname'
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/disqus.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/disqus.min.js"></script>
|
||||
```
|
||||
|
||||
## Gitalk
|
||||
|
|
@ -134,10 +134,10 @@ Disqus评论系统支持。 https://disqus.com/
|
|||
[Gitalk](https://github.com/gitalk/gitalk)，一个现代化的，基于Preact和Github Issue的评论系统。
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/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 src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/gitalk.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script>
|
||||
<script>
|
||||
const gitalk = new Gitalk({
|
||||
clientID: 'Github Application Client ID',
|
||||
|
|
@ -156,8 +156,8 @@ Disqus评论系统支持。 https://disqus.com/
|
|||
docsify的分页导航插件，由[@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>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
|
||||
```
|
||||
|
||||
从[这里](https://github.com/imyelo/docsify-pagination#readme)获取更多信息。
|
||||
|
|
@ -195,7 +195,7 @@ check [document](https://github.com/827652549/docsify-count)
|
|||
> Code Fund 以前叫 codesponsor
|
||||
|
||||
```
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
|
|
@ -203,3 +203,15 @@ window.$docsify = {
|
|||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Tabs
|
||||
|
||||
这个插件用来在 Markdown 中显示选项卡。
|
||||
|
||||
- [文档和示例](https://jhildenbiddle.github.io/docsify-tabs)
|
||||
|
||||
开发：[@jhildenbiddle](https://github.com/jhildenbiddle/docsify-tabs).
|
||||
|
||||
## 更多插件
|
||||
|
||||
参考 [awesome-docsify](awesome?id=plugins)
|
||||
|
|
|
|||
2
pwa.md
2
pwa.md
|
|
@ -22,7 +22,7 @@ const HOSTNAME_WHITELIST = [
|
|||
self.location.hostname,
|
||||
'fonts.gstatic.com',
|
||||
'fonts.googleapis.com',
|
||||
'unpkg.com'
|
||||
'cdn.jsdelivr.net'
|
||||
]
|
||||
|
||||
// The Util Function to hack URLs of intercepted requests
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ docsify serve docs
|
|||
<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">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
|
|
@ -56,7 +56,7 @@ docsify serve docs
|
|||
//...
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
|
@ -71,15 +71,17 @@ cd docs && python -m SimpleHTTPServer 3000
|
|||
|
||||
初始化时会显示 `Loading...` 内容，你可以自定义提示信息。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<div id="app">加载中</div>
|
||||
```
|
||||
|
||||
如果更改了 `el` 的配置，需要将该元素加上 `data-app` 属性。
|
||||
|
||||
*index.html*
|
||||
```html
|
||||
<!-- index.html -->
|
||||
<div data-app id="main">加载中</div>
|
||||
|
||||
<script>
|
||||
|
|
@ -88,3 +90,5 @@ cd docs && python -m SimpleHTTPServer 3000
|
|||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
对比 [el 设置](configuration.md#el)
|
||||
|
|
|
|||
90
ssr.md
90
ssr.md
|
|
@ -8,6 +8,9 @@
|
|||
|
||||
文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。
|
||||
|
||||
## 什么是 SSR?
|
||||
- 更好的 SEO
|
||||
- 更酷的感觉
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
|
@ -15,47 +18,56 @@
|
|||
如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。
|
||||
|
||||
```bash
|
||||
mkdir my-ssr-demo && cd my-ssr-demo
|
||||
npm init -y
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
配置 `package.json`
|
||||
编辑 `package.json`。假设你的文档放在 `./docs` 子目录。
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-project",
|
||||
"scripts": {
|
||||
"start": "docsify start .",
|
||||
"start": "docsify start . -c ssr.config.js",
|
||||
"deploy": "now -p"
|
||||
},
|
||||
"files": [
|
||||
"docs"
|
||||
],
|
||||
"docsify": {
|
||||
"config": {
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true
|
||||
"loadNavbar": true,
|
||||
"coverpage": true,
|
||||
"name": "docsify"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。其中 `basePath` 为文档所在的路径，可以填你的 docsify 文档网站。
|
||||
如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。
|
||||
|
||||
配置可以单独写在配置文件内，然后通过 `--config config.js` 加载。
|
||||
!> 其中 `basePath` 相当于 webpack 的 `publicPath ，为文档所在的路径，可以填你的 docsify 文档网站。我们可以使用本地或者远程文件。
|
||||
|
||||
渲染的基础模版也可以自定义，配置在 `template` 属性上，例如
|
||||
配置好了以后，我们可以在本地预览。
|
||||
|
||||
```js
|
||||
"docsify": {
|
||||
"template": "./ssr.html",
|
||||
"config": {
|
||||
"basePath": "https://docsify.js.org/",
|
||||
"loadSidebar": true,
|
||||
"loadNavbar": true
|
||||
}
|
||||
}
|
||||
```bash
|
||||
npm start
|
||||
|
||||
# open http://localhost:4000
|
||||
```
|
||||
|
||||
*ssr.html*
|
||||
Publish it!
|
||||
|
||||
```bash
|
||||
now -p
|
||||
```
|
||||
|
||||
Now, You have a support for SSR the docs site.
|
||||
|
||||
## 定制模板
|
||||
|
||||
你可以提供一个整页模板，例如：
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
|
|
@ -63,38 +75,50 @@ npm i now docsify-cli -D
|
|||
<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">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" title="vue">
|
||||
</head>
|
||||
<body>
|
||||
<!--inject-app-->
|
||||
<!--inject-config-->
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-markdown.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-nginx.min.js"></script>
|
||||
</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 和配置内容注入到页面上。
|
||||
模板可以包含占位符，会自动将渲染后的 html 和配置内容注入到页面上。
|
||||
|
||||
现在，你可以运行 `npm start` 预览效果，如果没有问题就通过 `npm run deploy` 部署服务。
|
||||
- `<!--inject-app-->`
|
||||
- `<!--inject-config-->`
|
||||
|
||||
```bash
|
||||
npm start
|
||||
# open http://localhost:4000
|
||||
|
||||
npm run deploy
|
||||
# now ...
|
||||
## 配置
|
||||
|
||||
配置可以单独写在配置文件内，然后通过 `--config config.js` 加载，或者写在 `package.json` 中。
|
||||
|
||||
渲染的基础模版也可以自定义，配置在 `template` 属性上。
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
template: './ssr.html',
|
||||
maxAge: 60 * 60 * 1000, // lru-cache 设置
|
||||
config: {
|
||||
// docsify 设置
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## 更多玩法
|
||||
|
||||
你可以直接在你的 Node 服务器上执行 `docsify start` 。
|
||||
|
||||
`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。
|
||||
|
||||
```js
|
||||
|
|
@ -103,7 +127,7 @@ var readFileSync = require('fs').readFileSync
|
|||
|
||||
// init
|
||||
var renderer = new Renderer({
|
||||
template: readFileSync('./docs/index.template.html', 'utf-8').,
|
||||
template: readFileSync('./docs/index.template.html', 'utf-8'),
|
||||
config: {
|
||||
name: 'docsify',
|
||||
repo: 'docsifyjs/docsify'
|
||||
|
|
|
|||
24
themes.md
24
themes.md
|
|
@ -3,21 +3,23 @@
|
|||
目前提供三套主题可供选择，模仿 [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">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.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">
|
||||
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dolphin.css">
|
||||
<!-- compressed -->
|
||||
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/buble.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/pure.css">
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dolphin.css">
|
||||
```
|
||||
|
||||
如果你有其他想法或者想开发别的主题，欢迎提 [PR](https://github.com/docsifyjs/docsify/pulls)。
|
||||
|
|
@ -40,8 +42,8 @@
|
|||
}
|
||||
|
||||
.demo-theme-preview a:hover {
|
||||
text-decoration: underline;
|
||||
cursor: pointer;
|
||||
text-decoration: underline;
|
||||
}
|
||||
</style>
|
||||
|
||||
|
|
|
|||
49
vue.md
49
vue.md
|
|
@ -8,8 +8,12 @@
|
|||
在 `index.html` 里引入 Vue。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/vue"></script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/vue"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify"></script>
|
||||
|
||||
<!-- 或者使用压缩版文件 -->
|
||||
<script src="//cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: '#main' })` 创建示例。
|
||||
|
|
@ -25,12 +29,12 @@
|
|||
<ul>
|
||||
<li v-for="i in 10">{{ i }}</li>
|
||||
</ul>
|
||||
``
|
||||
```
|
||||
|
||||
<ul>
|
||||
<li v-for="i in 10">{{ i }}</li>
|
||||
</ul>
|
||||
```
|
||||
````
|
||||
|
||||
当然你也可以手动初始化 Vue，这样你可以自定义一些配置。
|
||||
|
||||
|
|
@ -39,7 +43,7 @@
|
|||
```markdown
|
||||
# Vue 的基本用法
|
||||
|
||||
<div>hello {{ msg }}</div>
|
||||
<div id="main">hello {{ msg }}</div>
|
||||
|
||||
<script>
|
||||
new Vue({
|
||||
|
|
@ -58,18 +62,18 @@
|
|||
*index.html*
|
||||
|
||||
```html
|
||||
<!-- inject css file -->
|
||||
<link rel="stylesheet" href="//unpkg.com/vuep/dist/vuep.css">
|
||||
<!-- 引入 CSS 文件 -->
|
||||
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/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>
|
||||
<!-- 引入 JavaScript 文件 -->
|
||||
<script src="//cdn.jsdelivr.net/npm/vue"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/vuep"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/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>
|
||||
<!-- 或引入压缩版文件 -->
|
||||
<script src="//cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/vuep/dist/vuep.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
|
||||
```
|
||||
|
||||
*README.md*
|
||||
|
|
@ -93,20 +97,5 @@
|
|||
</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/)。
|
||||
|
|
|
|||
|
|
@ -6,40 +6,41 @@ docsify 提供了一套插件机制，其中提供的钩子（hook）支持处
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
function (hook, vm) {
|
||||
hook.init(function() {
|
||||
// 初始化时调用，只调用一次，没有参数。
|
||||
})
|
||||
plugins: [
|
||||
function(hook, vm) {
|
||||
hook.init(function() {
|
||||
// 初始化完成后调用，只调用一次，没有参数。
|
||||
});
|
||||
|
||||
hook.mounted(function() {
|
||||
// 初始化完成后调用，只调用一次，没有参数。
|
||||
})
|
||||
hook.beforeEach(function(content) {
|
||||
// 每次开始解析 Markdown 内容时调用
|
||||
// ...
|
||||
return content;
|
||||
});
|
||||
|
||||
hook.beforeEach(function(content) {
|
||||
// 每次开始解析 Markdown 内容时调用
|
||||
// ...
|
||||
return content
|
||||
})
|
||||
hook.afterEach(function(html, next) {
|
||||
// 解析成 html 后调用。
|
||||
// beforeEach 和 afterEach 支持处理异步逻辑
|
||||
// ...
|
||||
// 异步处理完成后调用 next(html) 返回结果
|
||||
next(html);
|
||||
});
|
||||
|
||||
hook.afterEach(function(html, next) {
|
||||
// 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑
|
||||
// ...
|
||||
// 异步处理完成后调用 next(html) 返回结果
|
||||
next(html)
|
||||
})
|
||||
hook.doneEach(function() {
|
||||
// 每次路由切换时数据全部加载完成后调用，没有参数。
|
||||
// ...
|
||||
});
|
||||
|
||||
hook.doneEach(function() {
|
||||
// 每次路由切换时数据全部加载完成后调用，没有参数。
|
||||
// ...
|
||||
})
|
||||
hook.mounted(function() {
|
||||
// 初始化并第一次加载完成数据后调用，只触发一次，没有参数。
|
||||
});
|
||||
|
||||
hook.ready(function() {
|
||||
// 初始化并第一次加载完成数据后调用，没有参数。
|
||||
})
|
||||
}
|
||||
]
|
||||
}
|
||||
hook.ready(function() {
|
||||
// 初始化并第一次加载完成数据后调用，没有参数。
|
||||
});
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
!> 如果需要用 docsify 的内部方法，可以通过 `window.Docsify` 获取，通过 `vm` 获取当前实例。
|
||||
|
|
@ -47,28 +48,28 @@ window.$docsify = {
|
|||
## 例子
|
||||
|
||||
|
||||
### footer
|
||||
#### footer
|
||||
|
||||
给每个页面的末尾加上 `footer`
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
plugins: [
|
||||
function (hook) {
|
||||
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('')
|
||||
].join('');
|
||||
|
||||
hook.afterEach(function (html) {
|
||||
return html + footer
|
||||
})
|
||||
hook.afterEach(function(html) {
|
||||
return html + footer;
|
||||
});
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -78,17 +79,35 @@ window.$docsify = {
|
|||
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'
|
||||
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
|
||||
})
|
||||
return (
|
||||
editHtml +
|
||||
html +
|
||||
'\n----\n' +
|
||||
'Last modified {docsify-updated} ' +
|
||||
editHtml
|
||||
);
|
||||
});
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 小技巧
|
||||
|
||||
### 获取 docsify 版本
|
||||
|
||||
```
|
||||
console.log(window.Docsify.version)
|
||||
```
|
||||
|
||||
当前版本: <span id='tip-version'>正在加载</span>
|
||||
|
||||
<script>
|
||||
document.getElementById('tip-version').innerText = Docsify.version
|
||||
</script>
|
||||
|
|
|
|||
Loading…
Reference in New Issue