+
+
+
diff --git a/packages/docs/docs/.vuepress/config.js b/packages/docs/docs/.vuepress/config.js
index 05f4513b..98f98849 100644
--- a/packages/docs/docs/.vuepress/config.js
+++ b/packages/docs/docs/.vuepress/config.js
@@ -42,7 +42,7 @@ module.exports = {
lastUpdated: 'Last Updated',
nav: require('./nav/en'),
sidebar: {
- '/guide/': genSidebarConfig('Guide')
+ '/guide/': genSidebarConfig('Guide', 'Advanced')
}
},
'/zh/': {
@@ -52,7 +52,7 @@ module.exports = {
lastUpdated: '上次更新',
nav: require('./nav/zh'),
sidebar: {
- '/zh/guide/': genSidebarConfig('指南')
+ '/zh/guide/': genSidebarConfig('指南', '深入')
}
}
}
@@ -71,22 +71,29 @@ module.exports = {
clientRootMixin: path.resolve(__dirname, 'mixin.js')
}
-function genSidebarConfig (title) {
+function genSidebarConfig (gruopA, groupB) {
return [
{
- title,
+ title: gruopA,
collapsable: false,
children: [
'',
'getting-started',
'directory-structure',
- 'permalinks',
'basic-config',
'assets',
'markdown',
'using-vue',
'i18n',
- 'deploy'
+ 'deploy',
+ ]
+ },
+ {
+ title: groupB,
+ collapsable: false,
+ children: [
+ 'permalinks',
+ 'markdown-slot'
]
}
]
diff --git a/packages/docs/docs/guide/markdown-slot.md b/packages/docs/docs/guide/markdown-slot.md
new file mode 100644
index 00000000..7fad111e
--- /dev/null
+++ b/packages/docs/docs/guide/markdown-slot.md
@@ -0,0 +1,101 @@
+# Markdown Slot
+
+VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component.
+
+## Why do I need Markdown Slot?
+
+First, let's review the relationship between layout components and markdown files:
+
+
+
+markdown files are providers of metadata (page content, configuration, etc.), and layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves pre-compile differences.
+
+Markdown Slot is to solve this kind of problem.
+
+## Named Slots
+
+You can define a named markdown slot through the following markdown syntax:
+
+``` md
+::: slot [$name]
+
+:::
+```
+
+Use the `Content` component to use the slot in the layout component:
+
+``` vue
+
+```
+
+## Default Slot Content
+
+By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component:
+
+``` vue
+
+```
+
+## Example
+
+Suppose your layout component is as follows:
+
+``` vue
+
+
+
+
+
+
+
+
+
+
+
+```
+
+If the markdown content of a page's is like this:
+
+```md
+::: slot header
+# Here might be a page title
+:::
+
+- A Paragraph
+- Another Paragraph
+
+::: slot footer
+Here's some contact info
+:::
+```
+
+Then the rendered HTML of this page will be:
+
+```html
+
+
+
+
Here might be a page title
+
+
+
+
+
+
A Paragraph
+
Another Paragraph
+
+
+
+
+
+```
+
+Note that:
+1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot.
+2. Please ensure the uniqueness of the slot defined.
diff --git a/packages/docs/docs/zh/guide/markdown-slot.md b/packages/docs/docs/zh/guide/markdown-slot.md
new file mode 100644
index 00000000..95f6c350
--- /dev/null
+++ b/packages/docs/docs/zh/guide/markdown-slot.md
@@ -0,0 +1,102 @@
+# Markdown 插槽
+
+VuePress 实现了一套针对 Markdown 的内容分发 API。通过这个特性，你可以将你的文档分割成多个片段，以便于在布局组件中灵活组合。
+
+## 为什么需要 Markdown 插槽
+
+首先，我们回顾一下布局组件和 Markdown 文件之间的关系：
+
+
+
+Markdown 文件是元数据（页面内容、配置等）的提供者，而布局组件负责消费他们。我们可以通过 frontmatter 来定义一些普通数据类型的元数据，但对于 Markdown/HTML 这种涉及到编译前差异的复杂元数据，frontmatter 却无能能力。
+
+Markdown 插槽便是为了解决这一类问题。
+
+## 具名插槽
+
+你可以通过下述的语法来定义一个具名 Markdown 插槽：
+
+``` md
+::: slot [$name]
+
+:::
+```
+
+在布局组件中利用 `Content` 组件来使用该插槽：
+
+``` vue
+
+```
+
+## 插槽的默认内容
+
+默认情况下，一个 Markdown 文件中的普通内容将会成为 Markdown 插槽的默认内容，你可以直接使用 `Content` 组件来访问它：
+
+``` vue
+
+```
+
+## 例子
+
+假设你的布局组件如下：
+
+``` vue
+
+
+
+
+
+
+
+
+
+
+
+```
+
+如果一个页面的 `markdown` 的内容是这样：
+
+```md
+::: slot header
+# Here might be a page title
+:::
+
+- A Paragraph
+- Another Paragraph
+
+::: slot footer
+Here's some contact info
+:::
+```
+
+那么这一页最终被渲染出的 HTML 将会是：
+
+```html
+