Update docs for 4.12.0 (#31)

This commit is contained in:
沈唁 2021-02-07 09:52:03 +08:00 committed by GitHub
parent 8db3d39d0a
commit 0b7485d99d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 456 additions and 64 deletions

View File

@ -464,6 +464,18 @@ window.$docsify = {
};
```
## crossOriginLinks
- type: `Array`
当设置了`routerMode:'history'`时,你可能会面临跨域的问题,参见 [#1379](https://github.com/docsifyjs/docsify/issues/1379) 。在 Markdown 内容中,有一个简单的方法可以解决,参见[helpers](zh-cn/helpers.md) 中的跨域链接。
```js
window.$docsify = {
crossOriginLinks: ['https://example.com/cross-origin-link'],
};
```
## noCompileLinks
- 类型: `Array`
@ -587,3 +599,104 @@ window.$docsify = {
topMargin: 90, // default: 0
};
```
## vueComponents
- type: `Object`
创建并注册全局 [Vue组件](https://vuejs.org/v2/guide/components.html) 。组件是以组件名称为键,以包含 Vue 选项的对象为值来指定的。组件`data`对每个实例都是唯一的,并且在用户浏览网站时不会持久。
```js
window.$docsify = {
vueComponents: {
'button-counter': {
template: `
<button @click="count += 1">
You clicked me {{ count }} times
</button>
`,
data() {
return {
count: 0,
};
},
},
},
};
```
```markdown
<button-counter></button-counter>
```
<output data-lang="output">
<button-counter></button-counter>
</output>
## vueGlobalOptions
- type: `Object`
指定 [Vue选项](https://vuejs.org/v2/api/#Options-Data) ,用于未明确使用[vueMounts](#mounting-dom-elements)、[vueComponents](#components)或[markdown脚本](#markdown-script)挂载的 Vue 内容。对全局`data`的更改将持续存在,并在任何使用全局引用的地方得到反映。
```js
window.$docsify = {
vueGlobalOptions: {
data() {
return {
count: 0,
};
},
},
};
```
```markdown
<p>
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</p>
```
<output data-lang="output">
<p>
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</p>
</output>
## vueMounts
- type: `Object`
指定要挂载为 [Vue实例](https://vuejs.org/v2/guide/instance.html) 的 DOM 元素及其相关选项。挂载元素使用 [CSS选择器](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) 作为键,并使用包含 Vue 选项的对象作为其值。每次加载新页面时Docsify 将挂载主内容区域中第一个匹配的元素。挂载元素`data`对每个实例来说都是唯一的,并且不会在用户浏览网站时持久存在。
```js
window.$docsify = {
vueMounts: {
'#counter': {
data() {
return {
count: 0,
};
},
},
},
};
```
```markdown
<div id="counter">
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</div>
```
<output id="counter">
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</output>

View File

@ -62,6 +62,12 @@
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
```
当执行全文搜索时,该插件会忽略双音符(例如,"cafe" 也会匹配 "café")。像 IE11 这样的旧版浏览器需要使用以下 [String.normalize()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) polyfill 来忽略双音符:
```html
<script src="//polyfill.io/v3/polyfill.min.js?features=String.prototype.normalize"></script>
```
## 谷歌统计 - Google Analytics
需要配置 track id 才能使用。
@ -91,6 +97,8 @@
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
```
?> 如果你不想解析成表情符号可以使用__colon_<span>_</span>或`&#58;`。如果你需要在标题中使用,我们建议使用`&#58;`。例如,`&#58;100:`。
## 外链脚本 - External Script
如果文档里的 script 是内联脚本,可以直接执行;而如果是外链脚本(即 js 文件内容由 `src` 属性引入),则需要使用此插件。

View File

@ -63,10 +63,14 @@ docsify serve docs
如果你的系统里安装了 Python 的话,也可以很容易地启动一个静态服务器去预览你的网站。
```bash
```python2
cd docs && python -m SimpleHTTPServer 3000
```
```python3
cd docs && python -m http.server 3000
```
## Loading 提示
初始化时会显示 `Loading...` 内容,你可以自定义提示信息。

407
vue.md
View File

@ -2,100 +2,367 @@
你可以直接在 Markdown 文件里写 Vue 代码,它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。
首先,将 Vue[2.x](https://vuejs.org) 或 [3.x](https://v3.vuejs.org) 添加到你的`index.html`文件中。
## 基础用法
为你的站点选择合适的生产版本或开发版本,以获得有用的控制台警告和 [Vue.js devtools](https://github.com/vuejs/vue-devtools) 支持。
`index.html` 里引入 Vue。
#### Vue 2.x
```html
<script src="//cdn.jsdelivr.net/npm/vue"></script>
<script src="//cdn.jsdelivr.net/npm/docsify"></script>
<!-- Production -->
<script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js"></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>
<!-- Development -->
<script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>
```
接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: '#main' })` 创建示例。
*README.md*
````markdown
# Vue 介绍
`v-for` 的用法
#### Vue 3.x
```html
<ul>
<li v-for="i in 10">{{ i }}</li>
</ul>
<!-- Production -->
<script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
<!-- Development -->
<script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js"></script>
```
<ul>
<li v-for="i in 10">{{ i }}</li>
</ul>
````
## 模板语法
当然你也可以手动初始化 Vue这样你可以自定义一些配置。
*README.md*
Vue[模板语法](https://vuejs.org/v2/guide/syntax.html) 用于创建动态内容。无需额外的配置,这种语法提供了一些有用的功能,如支持 [JavaScript表达式](https://vuejs.org/v2/guide/syntax.html#Using-JavaScript-Expressions) 和 Vue[指令](https://vuejs.org/v2/guide/syntax.html#Directives) 的循环和条件渲染。
```markdown
# Vue 的基本用法
<!-- 在docsify中隐藏在其他地方显示如GitHub-->
<p v-if="false">Text for GitHub</p>
<div id="main">hello {{ msg }}</div>
<!-- Sequenced content (i.e. loop)-->
<ul>
<li v-for="i in 3">Item {{ i }}</li>
</ul>
<!-- JavaScript expressions -->
<p>2 + 2 = {{ 2 + 2 }}</p>
```
<output data-lang="output">
<p v-if="false">Text for GitHub</p>
<ul>
<li v-for="i in 3">Item {{ i }}</li>
</ul>
<p>2 + 2 = {{ 2 + 2 }}</p>
</output>
[在GitHub上查看输出](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#template-syntax)
当使用[data](#data)、[computed properties](#computed-properties)、[methods](#methods)和[lifecycle hooks](#lifecycle-hooks)时Vue内容会变得更加有趣。这些选项可以作为[全局选项](#global-options)或在DOM中的[mounts](#mounts)和[component](#components)来指定。
### Data
```js
{
data() {
return {
message: 'Hello, World!'
};
}
}
```
<!-- prettier-ignore-start -->
```markdown
<!-- 在docsify中显示消息在其他地方显示 "{{ message }}"例如GitHub -->
{{ message }}
<!-- 在docsify中显示消息在其他地方隐藏例如GitHub -->
<p v-text="message"></p>
<!-- 在docsify中显示消息在其他地方显示 text例如GitHub -->
<p v-text="message">Text for GitHub</p>
```
<!-- prettier-ignore-end -->
<output data-lang="output">
{{ message }}
<p v-text="message"></p>
<p v-text="message">Text for GitHub</p>
</output>
[在GitHub上查看输出](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#data)
### Computed properties
```js
{
computed: {
timeOfDay() {
const date = new Date();
const hours = date.getHours();
if (hours < 12) {
return 'morning';
}
else if (hours < 18) {
return 'afternoon';
}
else {
return 'evening'
}
}
},
}
```
```markdown
Good {{ timeOfDay }}!
```
<output data-lang="output">
Good {{ timeOfDay }}!
</output>
### Methods
```js
{
data() {
return {
message: 'Hello, World!'
};
},
methods: {
hello() {
alert(this.message);
}
},
}
```
```markdown
<button @click="hello">Say Hello</button>
```
<output data-lang="output">
<p><button @click="hello">Say Hello</button></p>
</output>
### Lifecycle Hooks
```js
{
data() {
return {
images: null,
};
},
created() {
fetch('https://api.domain.com/')
.then(response => response.json())
.then(data => (this.images = data))
.catch(err => console.log(err));
}
}
// API response:
// [
// { title: 'Image 1', url: 'https://domain.com/1.jpg' },
// { title: 'Image 2', url: 'https://domain.com/2.jpg' },
// { title: 'Image 3', url: 'https://domain.com/3.jpg' },
// ];
```
```markdown
<div style="display: flex;">
<figure style="flex: 1;">
<img v-for="image in images" :src="image.url" :title="image.title">
<figcaption>{{ image.title }}</figcaption>
</figure>
</div>
```
<output data-lang="output">
<div style="display: flex;">
<figure v-for="image in images" style="flex: 1; text-align: center;">
<img :src="image.url">
<figcaption>{{ image.title }}</figcaption>
</figure>
</div>
</output>
## Global options
使用`vueGlobalOptions`来指定 [Vue options](https://vuejs.org/v2/api/#Options-Data) ,用于未明确挂载[vueMounts](#mounts)、[vueComponents](#components)或[markdown脚本](#markdown-script)的Vue内容。对全局`data`的更改将持续存在,并反映在任何使用全局引用的地方。
```js
window.$docsify = {
vueGlobalOptions: {
data() {
return {
count: 0,
};
},
},
};
```
```markdown
<p>
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</p>
```
<output data-lang="output">
<p>
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</p>
</output>
请注意当多个全局计数器呈现时的行为:
<output data-lang="output">
<p>
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</p>
</output>
对一个计数器的更改会影响两个计数器。这是因为两个实例都引用了相同的全局`count`值。现在,导航到一个新的页面,并返回本节,查看对全局数据的更改如何在页面加载之间持久化。
## Mounts
使用`vueMounts`来指定要挂载为 [Vue实例](https://vuejs.org/v2/guide/instance.html) 的DOM元素及其相关选项。挂载元素使用 [CSS选择器](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) 作为键并使用一个包含Vue选项的对象作为其值。每次加载新页面时Docsify将挂载主内容区域中第一个匹配的元素。挂载元素`data`对每个实例来说都是唯一的,并且在用户浏览网站时不会持久。
```js
window.$docsify = {
vueMounts: {
'#counter': {
data() {
return {
count: 0,
};
},
},
},
};
```
```markdown
<div id="counter">
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</div>
```
<output id="counter">
<button @click="count -= 1">-</button>
{{ count }}
<button @click="count += 1">+</button>
</output>
## Components
使用`vueComponents`创建和注册全局[Vue组件](https://vuejs.org/v2/guide/components.html) 。组件是以组件名称为键以包含Vue选项的对象为值来指定的。组件`data`对每个实例来说都是唯一的,并且在用户浏览网站时不会持久存在。
```js
window.$docsify = {
vueComponents: {
'button-counter': {
template: `
<button @click="count += 1">
You clicked me {{ count }} times
</button>
`,
data() {
return {
count: 0,
};
},
},
},
};
```
```markdown
<button-counter></button-counter>
<button-counter></button-counter>
```
<output data-lang="output">
<button-counter></button-counter>
<button-counter></button-counter>
</output>
## Markdown script
Vue内容可以使用 Markdown 页面中的`<script>`
!> 只有 Markdown 文件中的第一个`<script>`使VueMarkdown
```html
<!-- Vue 2.x -->
<script>
new Vue({
el: '#main',
data: { msg: 'Vue' }
})
el: '#example',
// Options...
});
</script>
```
!> 一个 Markdown 文件里只有第一个 `script` 标签内的内容会被执行。
## 搭配 Vuep 写 Playground
[Vuep](https://github.com/QingWei-Li/vuep) 是一个提供在线编辑和预览效果的 Vue 组件,搭配 docsify 可以直接在文档里写 Vue 的示例代码,支持 Vue component spec 和 JSX。
*index.html*
```html
<!-- 引入 CSS 文件 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/vuep/dist/vuep.css">
<!-- 引入 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>
<!-- 或引入压缩版文件 -->
<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*
```markdown
# Vuep 使用
<vuep template="#example"></vuep>
<script v-pre type="text/x-template" id="example">
<template>
<div>Hello, {{ name }}!</div>
</template>
<!-- Vue 3.x -->
<script>
module.exports = {
data: function () {
return { name: 'Vue' }
}
}
</script>
Vue.createApp({
// Options...
}).mount('#example');
</script>
```
## Technical Notes
?> 具体效果参考 [Vuep 文档](https://qingwei-li.github.io/vuep/)。
- Docsify processes Vue content in the following order on each page load:
1. Execute markdown `<script>`
1. Register global `vueComponents`
1. Mount `vueMounts`
1. Auto-mount unmounted `vueComponents`
1. Auto-mount unmounted Vue template syntax using `vueGlobalOptions`
- When auto-mounting Vue content, docsify will mount each top-level element in your markdown that contains template syntax or a component. For example, in the following HTML the top-level `<p>`, `<my-component />`, and `<div>` elements will be mounted.
```html
<p>{{ foo }}</p>
<my-component />
<div>
<span>{{ bar }}</span>
<some-other-component />
</div>
```
- Docsify will not mount an existing Vue instance or an element that contains an existing Vue instance.
- Docsify will automatically destroy/unmount all Vue instances it creates before each page load.
## 说明
- Docsify 在每次加载页面时按以下顺序处理Vue内容
1.执行 Markdown `<script>`
1.注册全局 `vueComponents`
1.挂载 `vueMounts`
1.自动挂载未安装的 `vueComponents`
1.使用 `vueGlobalOptions` 自动挂载未安装的Vue模板语法
- 自动挂载Vue内容时docsify将挂载Markdown中包含模板语法或组件的每个顶级元素。例如在以下HTML中将安装顶级`<p>``<my-component />`和`<div>`元素。
```html
<p>{{ foo }}</p>
<my-component />
<div>
<span>{{ bar }}</span>
<some-other-component />
</div>
```
- Docsify将不会挂载现有Vue实例或包含现有Vue实例的元素。
- Docsify将在每次加载页面之前自动销毁/卸载其创建的所有Vue实例。