docs(en) finish
This commit is contained in:
qingwei.li
parent
68c70509d1
commit
7c6ab54ba7
34 changed files with 949 additions and 558 deletions
|
|
@ -6,9 +6,9 @@
|
|||
|
||||
docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。
|
||||
|
||||
这将非常实用，如果只是需要快速的写一个小型的文档，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。
|
||||
这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。
|
||||
|
||||
可以查看[快速开始](zh-cn/quickstart)一章了解详情。
|
||||
查看[快速开始](zh-cn/quickstart)了解详情。
|
||||
|
||||
## 特性
|
||||
- 无需构建，写完文档直接发布
|
||||
|
|
@ -24,4 +24,4 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo
|
|||
|
||||
## 捐赠
|
||||
|
||||
如果你觉得 docsify 对你有帮助，或者想对我微小的工作一些资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。
|
||||
如果你觉得 docsify 对你有帮助，或者想对我微小的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# CDN
|
||||
|
||||
推荐使用 [UNPKG](//unpkg.com) —— 能及时获取到最新版。
|
||||
推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。
|
||||
|
||||
## 获取最新版本
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 配置项
|
||||
|
||||
docsify 有两种配置参数的方式。一种是配置 `window.$docsify` 对象，另一种是给 `script` 标签添加 `data-*` 属性。
|
||||
docsify 有两种配置参数的方式。一种是配置在 `window.$docsify` 里，另一种是给 `script` 标签添加 `data-*` 属性。
|
||||
|
||||
```html
|
||||
<!-- 方法 1 -->
|
||||
|
|
@ -137,7 +137,7 @@ window.$docsify = {
|
|||
- 类型：`String`
|
||||
- 默认值: `README.md`
|
||||
|
||||
设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染，或者是文档在仓库根目录的情况使用。
|
||||
设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染，或者是文档存放在其他位置的情况使用。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
|
|
@ -162,7 +162,7 @@ window.$docsify = {
|
|||
// 直接渲染其他域名的文档
|
||||
basePath: 'https://docsify.js.org/',
|
||||
|
||||
// 甚至直接渲染其他仓库下的内容
|
||||
// 甚至直接渲染其他仓库 readme
|
||||
basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
|
||||
}
|
||||
```
|
||||
|
|
@ -216,11 +216,20 @@ window.$docsify = {
|
|||
|
||||
参考 [Markdown 配置](/zh-cn/markdown)。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
markdown: function (marked, renderer) {
|
||||
// ...
|
||||
return marked
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## theme-color
|
||||
|
||||
- 类型：`String`
|
||||
|
||||
替换默认的主题配置。利用 CSS3 支持变量的特性，对于老的浏览器有 polyfill 处理。
|
||||
替换主题色。利用 [CSS3 支持变量]((https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables)的特性，对于老的浏览器有 polyfill 处理。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
|
|
@ -230,6 +239,8 @@ window.$docsify = {
|
|||
|
||||
## alias
|
||||
|
||||
- 类型：`Object`
|
||||
|
||||
定义路由别名，可以更自由的定义路由规则。
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
# 封面
|
||||
|
||||
一个有封面的文档网站会给用户留下好的印象，通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见见[配置项#coverpage](zh-cn/configuration#coverpage)。
|
||||
通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见[配置项#coverpage](zh-cn/configuration#coverpage)。
|
||||
|
||||
## 基本用法
|
||||
|
||||
封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。
|
||||
封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。渲染效果如本文档。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<script>
|
||||
|
|
@ -33,7 +35,7 @@
|
|||
[Get Started](#quick-start)
|
||||
```
|
||||
|
||||
渲染效果如本文档。
|
||||
|
||||
|
||||
!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。
|
||||
|
||||
|
|
@ -41,6 +43,8 @@
|
|||
|
||||
目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。
|
||||
|
||||
*_coverpage.md*
|
||||
|
||||
```markdown
|
||||
# docsify
|
||||
|
||||
|
|
@ -52,4 +56,3 @@
|
|||
<!-- 背景色 -->
|
||||
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@
|
|||
|
||||
## 配置文件
|
||||
|
||||
如果不想手工写导航栏组件，或者需要根据不同目录加载不同的导航栏，那我们可以通过 Markdown 文件来配置。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#load-navbar](zh-cn/configuration#load-navbar)一节。
|
||||
那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#load-navbar](zh-cn/configuration#load-navbar)。
|
||||
|
||||
*index.html*
|
||||
|
||||
|
|
@ -51,7 +51,7 @@
|
|||
- 基础
|
||||
- [快速开始](zh-cn/quickstart)
|
||||
- [多页文档](zh-cn/more-pages)
|
||||
- [嵌套导航栏](zh-cn/custom-navbar)
|
||||
- [定制导航栏](zh-cn/custom-navbar)
|
||||
- [封面](zh-cn/cover)
|
||||
|
||||
- 配置
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。
|
||||
|
||||
## 部署 GitHub Pages
|
||||
## GitHub Pages
|
||||
|
||||
GitHub Pages 支持从三个地方读取文件
|
||||
- `docs/` 目录
|
||||
|
|
@ -15,9 +15,9 @@ GitHub Pages 支持从三个地方读取文件
|
|||
|
||||
!> 可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。
|
||||
|
||||
## 部署 VPS
|
||||
## VPS
|
||||
|
||||
和部署所有静态网站一样，将服务器的访问根目录设定为 `index.html` 文件。
|
||||
和部署所有静态网站一样，只需将服务器的访问根目录设定为 `index.html` 文件。
|
||||
|
||||
例如 nginx 的配置
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。
|
|||
|
||||
## 普通提示
|
||||
|
||||
不重要的提示信息，比如写 TODO 或者参考内容等。
|
||||
普通的提示信息，比如写 TODO 或者参考内容等。
|
||||
|
||||
```markdown
|
||||
?> *TODO* 完善示例
|
||||
|
|
|
|||
|
|
@ -8,4 +8,4 @@
|
|||
<script src="//unpkg.com/prismjs/components/prism-php.js"></script>
|
||||
```
|
||||
|
||||
其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。
|
||||
?> 其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Markdown 配置
|
||||
|
||||
内置的 Markdown 解析插件是 [marked](https://github.com/chjj/marked)，可以修改它的配置。
|
||||
内置的 Markdown 解析器是 [marked](https://github.com/chjj/marked)，可以修改它的配置。
|
||||
|
||||
```js
|
||||
window.$docsify = {
|
||||
|
|
@ -17,7 +17,7 @@ window.$docsify = {
|
|||
|
||||
```js
|
||||
window.$docsify = {
|
||||
markdown: function(marked) {
|
||||
markdown: function(marked, renderer) {
|
||||
// ...
|
||||
|
||||
return marked
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# 多页文档
|
||||
|
||||
如果需要创建多个页面，或者需要提供多语言的文档。在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。
|
||||
如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。
|
||||
|
||||
一个简单的例子：
|
||||
假设你的目录结构如下：
|
||||
|
||||
```text
|
||||
-| docs/
|
||||
|
|
@ -26,7 +26,7 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
|||
|
||||
默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。
|
||||
|
||||
首先配置 docsify 的 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)一节。
|
||||
首先配置 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)。
|
||||
|
||||
```html
|
||||
<script>
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
```html
|
||||
<script>
|
||||
window.$docsify = {
|
||||
search: 'auto', // 默认配置，window.$docsify.search 可以不用配置
|
||||
search: 'auto', // 默认值
|
||||
|
||||
search : [
|
||||
'/', // => /README.md
|
||||
|
|
@ -54,7 +54,7 @@
|
|||
|
||||
## 自定义插件
|
||||
|
||||
docsify 提供了一套插件注册机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。
|
||||
docsify 提供了一套插件机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。
|
||||
|
||||
#### 完整功能
|
||||
|
||||
|
|
@ -65,17 +65,20 @@ window.$docsify = {
|
|||
hook.init(function() {
|
||||
// 初始化时调用，只调用一次
|
||||
})
|
||||
|
||||
hook.beforeEach(function(content) {
|
||||
// 每次开始解析 Markdown 内容时调用
|
||||
// ...
|
||||
return content
|
||||
})
|
||||
|
||||
hook.afterEach(function(html, next) {
|
||||
// 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑
|
||||
// ...
|
||||
// 处理完成后调用 next(html) 返回结果
|
||||
// 异步处理完成后调用 next(html) 返回结果
|
||||
next(html)
|
||||
})
|
||||
|
||||
hook.ready(function() {
|
||||
// docsify 初始化完成后调用，只调用一次
|
||||
})
|
||||
|
|
|
|||
|
|
@ -36,7 +36,9 @@ docsify serve docs
|
|||
|
||||
## 手动初始化
|
||||
|
||||
如果不喜欢 npm 安装工具，或者不需要本地预览文档功能，我们其实只需要直接创建一个 `index.html` 文件。
|
||||
如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 `index.html` 文件。
|
||||
|
||||
*index.html*
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
# 主题
|
||||
|
||||
目前提供两套主题可供选择，模仿 [vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式，引入其中之一即可。
|
||||
目前提供三套主题可供选择，模仿 [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">
|
||||
```
|
||||
|
||||
!> CSS 的压缩文件位于 `/lib/themes/`
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
# 兼容 Vue
|
||||
|
||||
Docsify 的一大特色是可以配合 Vue 一起使用。你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。
|
||||
你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。
|
||||
|
||||
|
||||
## 基础用法
|
||||
|
||||
用法很简单，首先在 `index.html` 里引入 Vue 脚本。
|
||||
在 `index.html` 里引入 Vue。
|
||||
|
||||
```html
|
||||
<script src="//unpkg.com/vue"></script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
接着就可以直接在 Markdown 里写 Vue 了。默认会自动执行 `new Vue({ el: 'main' })` 脚本。
|
||||
接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: 'main' })` 创建示例。
|
||||
|
||||
*README.md*
|
||||
|
||||
|
|
@ -40,6 +40,7 @@ Docsify 的一大特色是可以配合 Vue 一起使用。你可以直接在 Mar
|
|||
# Vue 的基本用法
|
||||
|
||||
<div>hello {{ msg }}</div>
|
||||
|
||||
<script>
|
||||
new Vue({
|
||||
el: 'main',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue