docs: document markdown slot

ulivz · ulivz · commit 3f79224148b3 · 2018-10-23T23:02:29.000+08:00
diff --git a/packages/docs/docs/.vuepress/components/diagram-markdown-slot-relationship.vue b/packages/docs/docs/.vuepress/components/diagram-markdown-slot-relationship.vue
@@ -0,0 +1,49 @@
+<template>
+  <svg-container>
+    <svg width="400px" viewBox="0 0 688 403" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+      <defs>
+        <rect id="path-1" x="140" y="0" width="549" height="176" rx="20"></rect>
+        <mask id="mask-2" maskContentUnits="userSpaceOnUse" maskUnits="objectBoundingBox" x="0" y="0" width="549" height="176" fill="white">
+          <use xlink:href="#path-1"></use>
+        </mask>
+      </defs>
+      <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="diagram-markdown-slot-relationship" transform="translate(-1.000000, 0.000000)">
+          <circle id="Oval" fill="#00BC7D" fill-rule="nonzero" cx="235" cy="88" r="59"></circle>
+          <text id="Markdown-File-1" font-family="PingFangSC-Regular, PingFang SC" font-size="20" font-weight="normal" fill="#FFFFFF">
+            <tspan x="186.79" y="85">Markdown </tspan>
+            <tspan x="211.43" y="113">File 1</tspan>
+          </text>
+          <circle id="Oval" fill="#00BC7D" fill-rule="nonzero" cx="415" cy="88" r="59"></circle>
+          <text id="Markdown-File-2" font-family="PingFangSC-Regular, PingFang SC" font-size="20" font-weight="normal" fill="#FFFFFF">
+            <tspan x="366.79" y="85">Markdown </tspan>
+            <tspan x="389.44" y="113">File 2</tspan>
+          </text>
+          <circle id="Oval" fill="#EB4D5D" fill-rule="nonzero" transform="translate(419.000000, 320.000000) rotate(-360.000000) translate(-419.000000, -320.000000) " cx="419" cy="320" r="83"></circle>
+          <text id="Layout-Component" transform="translate(419.000000, 320.000000) rotate(-360.000000) translate(-419.000000, -320.000000) " font-family="PingFangSC-Regular, PingFang SC" font-size="24" font-weight="normal" fill="#FFFFFF">
+            <tspan x="381.272" y="312">Layout</tspan>
+            <tspan x="354.572" y="345">Component</tspan>
+          </text>
+          <circle id="Oval" fill="#00BC7D" fill-rule="nonzero" cx="595" cy="88" r="59"></circle>
+          <text id="Markdown-File-3" font-family="PingFangSC-Regular, PingFang SC" font-size="20" font-weight="normal" fill="#FFFFFF">
+            <tspan x="546.79" y="85">Markdown </tspan>
+            <tspan x="569.44" y="113">File 3</tspan>
+          </text>
+          <use id="Rectangle" stroke="#DC585F" mask="url(#mask-2)" stroke-width="8" stroke-dasharray="5" fill-rule="nonzero" xlink:href="#path-1"></use>
+          <path id="Path" d="M317.737594,275.914863 C316.399837,275.439513 315.071319,274.934993 313.752054,274.40131 L314.877079,271.620246 C316.062011,272.099587 317.254567,272.554642 318.454758,272.985416 L320.320183,265.365584 L336.516196,279.111098 L315.802177,283.8206 L317.737594,275.914863 Z M237.053972,153.839171 L240.036678,154.160829 C239.860222,155.797097 239.727284,157.431576 239.637858,159.064293 L236.642347,158.900223 C236.734662,157.214791 236.871873,155.527765 237.053972,153.839171 Z M236.500062,163.984683 L239.50006,163.988115 C239.498183,165.6288 239.540423,167.267783 239.626781,168.905092 L236.630945,169.063103 C236.541751,167.372018 236.498123,165.679201 236.500062,163.984683 Z M237.034923,174.12831 L240.017951,173.809652 C240.191774,175.436839 240.409353,177.062453 240.670697,178.686519 L237.708802,179.163147 C237.439026,177.486687 237.214397,175.808399 237.034923,174.12831 Z M238.651506,184.177472 L241.584397,183.54648 C241.927872,185.142975 242.313817,186.738038 242.742248,188.33169 L239.845114,189.110544 C239.40355,187.46804 239.005676,185.823676 238.651506,184.177472 Z M241.277699,193.960604 L244.133333,193.041173 C244.633282,194.593949 245.173728,196.145426 245.754688,197.695614 L242.945486,198.748412 C242.348064,197.154297 241.792129,195.558357 241.277699,193.960604 Z M244.837653,203.467846 L247.596505,202.289399 C248.237243,203.789426 248.91606,205.288264 249.632972,206.785917 L246.927022,208.081229 C246.191725,206.545169 245.495264,205.007373 244.837653,203.467846 Z M249.214331,212.61803 L251.865379,211.213771 C252.629062,212.6555 253.428173,214.096132 254.262722,215.535667 L251.667331,217.040308 C250.813682,215.567829 249.996012,214.093736 249.214331,212.61803 Z M254.297283,221.391099 L256.836394,219.793315 C257.706019,221.175275 258.60841,222.556214 259.543577,223.936131 L257.060143,225.61915 C256.106032,224.21128 255.185076,222.801931 254.297283,221.391099 Z M259.974465,229.772936 L262.402649,228.01114 C263.362565,229.334138 264.3527,230.656183 265.373059,231.977271 L262.998786,233.811072 C261.960192,232.466375 260.952083,231.120331 259.974465,229.772936 Z M266.091044,237.698109 L268.411267,235.796382 C269.468483,237.08625 270.534696,238.346975 271.6099,239.578562 L269.349958,241.551545 C268.25419,240.296403 267.167887,239.011923 266.091044,237.698109 Z M272.734865,245.303177 L274.928459,243.25668 C276.064358,244.474225 277.209951,245.660334 278.365233,246.815016 L276.244465,248.936888 C275.064352,247.757389 273.894487,246.546149 272.734865,245.303177 Z M279.887015,252.446537 L281.927895,250.247718 C283.145938,251.378269 284.374389,252.475061 285.613248,253.538106 L283.65964,255.814817 C282.391056,254.726266 281.133515,253.603502 279.887015,252.446537 Z M287.576785,259.039625 L289.435074,256.684468 C290.736664,257.711462 292.049366,258.702468 293.373181,259.657502 L291.617984,262.09046 C290.259116,261.110138 288.912049,260.093188 287.576785,259.039625 Z M295.785278,264.957777 L297.4295,262.448487 C298.812943,263.354993 300.208145,264.223547 301.615114,265.054165 L300.089978,267.637566 C298.64262,266.783104 297.207718,265.889835 295.785278,264.957777 Z M304.529995,270.116457 L305.928241,267.462232 C307.386943,268.230677 308.857919,268.959729 310.341185,269.649406 L309.076317,272.36972 C307.547965,271.659079 306.032519,270.907986 304.529995,270.116457 Z" fill="#8599A4" fill-rule="nonzero"></path>
+          <path id="Path" d="M505.524249,279.462157 L520.680172,264.577668 L526.525394,282.656202 L505.524249,279.462157 Z M607.459883,153.645338 L610.450216,153.404698 C610.586546,155.098816 610.691833,156.77921 610.766069,158.445876 L607.76904,158.579368 C607.696405,156.948625 607.593356,155.303949 607.459883,153.645338 Z M607.896371,163.523725 L610.896305,163.503827 C610.907594,165.205698 610.885378,166.892755 610.829647,168.56499 L607.831312,168.465065 C607.885706,166.832931 607.907396,165.18582 607.896371,163.523725 Z M607.562992,173.41012 L610.554458,173.636245 C610.42622,175.332733 610.262196,177.013376 610.062375,178.678161 L607.083754,178.320643 C607.278311,176.69972 607.43806,175.062883 607.562992,173.41012 Z M606.384557,183.20243 L609.343631,183.696275 C609.063719,185.373481 608.746022,187.033908 608.390534,188.677536 L605.458331,188.043351 C605.803721,186.446416 606.112465,184.832782 606.384557,183.20243 Z M604.291922,192.859811 L607.189213,193.63808 C606.748727,195.277893 606.269015,196.900206 605.750076,198.504997 L602.895608,197.581952 C603.399033,196.025135 603.864471,194.451096 604.291922,192.859811 Z M601.271525,202.20035 L604.075335,203.267423 C603.472603,204.851146 602.829959,206.41696 602.147412,207.96484 L599.402435,206.754426 C600.064131,205.253832 600.687158,203.735815 601.271525,202.20035 Z M597.290807,211.224832 L599.969243,212.576121 C599.208118,214.084773 598.407288,215.575496 597.566769,217.048269 L594.961228,215.561273 C595.776314,214.133064 596.552836,212.687591 597.290807,211.224832 Z M592.397896,219.797817 L594.924421,221.41543 C594.015938,222.834374 593.068787,224.235757 592.082984,225.619564 L589.639589,223.878927 C590.596732,222.53535 591.516161,221.174984 592.397896,219.797817 Z M586.660862,227.851867 L589.017105,229.708777 C587.977352,231.028126 586.900649,232.33062 585.787016,233.616254 L583.51944,231.652049 C584.602788,230.401378 585.649923,229.134653 586.660862,227.851867 Z M580.265616,235.264939 L582.455796,237.315088 C581.30524,238.54423 580.129172,239.752667 578.927599,240.940392 L576.818608,238.806814 C577.992605,237.646347 579.141605,236.465724 580.265616,235.264939 Z M573.232259,242.218017 L575.257873,244.430909 C574.018262,245.565611 572.753689,246.680004 571.464163,247.774085 L569.523296,245.486502 C570.784152,244.416746 572.02047,243.327252 573.232259,242.218017 Z M565.69619,248.613677 L567.551459,250.971213 C566.232998,252.008779 564.890366,253.026639 563.523572,254.024792 L561.754283,251.602063 C563.092093,250.625076 564.406059,249.628948 565.69619,248.613677 Z M557.696251,254.45734 L559.379522,256.940603 C557.993427,257.880163 556.584154,258.800801 555.151714,259.702516 L553.553517,257.163665 C554.957366,256.279948 556.338275,255.377839 557.696251,254.45734 Z M549.296271,259.746128 L550.810006,262.336225 C549.366211,263.180025 547.900334,264.005779 546.412381,264.81349 L544.981154,262.176903 C546.441447,261.384207 547.879818,260.573948 549.296271,259.746128 Z M540.616615,264.460914 L541.967561,267.139522 C540.476204,267.891683 538.963914,268.626729 537.430695,269.344665 L536.158499,266.62777 C537.665372,265.922171 539.15141,265.199884 540.616615,264.460914 Z M531.631899,268.669952 L532.82743,271.421444 C531.297326,272.086278 529.747462,272.734956 528.17784,273.367482 L527.056524,270.58492 C528.601359,269.962383 530.126483,269.324059 531.631899,268.669952 Z" fill="#8599A4" fill-rule="nonzero"></path>
+          <path id="Line" d="M415,229 L405.5,210 L424.5,210 L415,229 Z M413.5,154 L416.5,154 L416.5,159 L413.5,159 L413.5,154 Z M413.5,164 L416.5,164 L416.5,169 L413.5,169 L413.5,164 Z M413.5,174 L416.5,174 L416.5,179 L413.5,179 L413.5,174 Z M413.5,184 L416.5,184 L416.5,189 L413.5,189 L413.5,184 Z M413.5,194 L416.5,194 L416.5,199 L413.5,199 L413.5,194 Z M413.5,204 L416.5,204 L416.5,209 L413.5,209 L413.5,204 Z" fill="#8599A4" fill-rule="nonzero"></path>
+          <text id="Provider" fill="#8599A4" font-family="Arial-Black, Arial Black" font-size="25" font-weight="700">
+            <tspan x="0.06640625" y="28">Provider</tspan>
+          </text>
+          <text id="Consumer" fill="#8599A4" font-family="Arial-Black, Arial Black" font-size="25" font-weight="700">
+            <tspan x="0.243896484" y="327">Consumer</tspan>
+          </text>
+          <path d="M161,320 L320.5,320" id="Line-2" stroke="#DC585F" stroke-width="4" stroke-dasharray="5" fill-rule="nonzero"></path>
+        </g>
+      </g>
+    </svg>
+  </svg-container>
+</template>
+
+
diff --git a/packages/docs/docs/.vuepress/components/svg-container.vue b/packages/docs/docs/.vuepress/components/svg-container.vue
@@ -0,0 +1,13 @@
+<template>
+  <div class="svg-container">
+    <slot></slot>
+  </div>
+</template>
+
+<style lang="stylus">
+  .svg-container
+    margin 30px auto
+    text-align center
+    & > svg
+      max-width 100%
+</style>
diff --git 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/.vuepress/mixin.js b/packages/docs/docs/.vuepress/mixin.js
@@ -33,6 +33,7 @@ const gotIt = {
 export default {
   methods: {
     notice () {
+      return false;
       setTimeout(() => {
         this.$notification = this.$toasted.show(notification[this.$localePath], {
           containerClass: 'compatibility-notification',
diff --git a/packages/docs/docs/guide/markdown-slot.md 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:
+
+<diagram-markdown-slot-relationship/>
+
+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
+<Content slot="$name"/> 
+```
+
+## 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
+<Content/>
+```
+
+## Example
+
+Suppose your layout component is as follows:
+
+``` vue
+<template>
+  <div class="container">
+    <header>
+      <Content slot="header"/>
+    </header>
+    <main>
+      <Content/>
+    </main>
+    <footer>
+      <Content slot="footer"/>
+    </footer>
+  </div>
+</template>
+```
+
+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
+<div class="container">
+  <header>
+    <div class="content header">
+      <h1>Here might be a page title</h1>
+    </div>
+  </header>
+  <main>
+    <div class="content default">
+      <ul>
+        <li>A Paragraph</li>
+        <li>Another Paragraph</li>
+      </ul>
+    </div>
+  </main>
+  <footer>
+    <div class="content footer">
+      <p>Here's some contact info</p>
+    </div>
+  </footer>
+</div>
+```
+
+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
@@ -0,0 +1,102 @@
+# Markdown 插槽
+
+VuePress 实现了一套针对 Markdown 的内容分发 API。通过这个特性，你可以将你的文档分割成多个片段，以便于在布局组件中灵活组合。
+
+## 为什么需要 Markdown 插槽
+
+首先，我们回顾一下布局组件和 Markdown 文件之间的关系：
+
+<diagram-markdown-slot-relationship/>
+
+Markdown 文件是元数据（页面内容、配置等）的提供者，而布局组件负责消费他们。我们可以通过 frontmatter 来定义一些普通数据类型的元数据，但对于 Markdown/HTML 这种涉及到编译前差异的复杂元数据，frontmatter 却无能能力。
+
+Markdown 插槽便是为了解决这一类问题。
+
+## 具名插槽
+
+你可以通过下述的语法来定义一个具名 Markdown 插槽：
+
+``` md
+::: slot [$name]
+
+:::
+```
+
+在布局组件中利用 `Content` 组件来使用该插槽：
+
+``` vue
+<Content slot="$name"/> 
+```
+
+## 插槽的默认内容
+
+默认情况下，一个 Markdown 文件中的普通内容将会成为 Markdown 插槽的默认内容，你可以直接使用 `Content` 组件来访问它：
+
+``` vue
+<Content/>
+```
+
+## 例子
+
+假设你的布局组件如下：
+
+``` vue
+<template>
+  <div class="container">
+    <header>
+      <Content slot="header"/>
+    </header>
+    <main>
+      <Content/>
+    </main>
+    <footer>
+      <Content slot="footer"/>
+    </footer>
+  </div>
+</template>
+```
+
+如果一个页面的 `markdown` 的内容是这样：
+
+```md
+::: slot header
+# Here might be a page title
+:::
+
+- A Paragraph
+- Another Paragraph
+
+::: slot footer
+Here's some contact info
+:::
+```
+
+那么这一页最终被渲染出的 HTML 将会是：
+
+```html
+<div class="container">
+  <header>
+    <div class="content header">
+      <h1>Here might be a page title</h1>
+    </div>
+  </header>
+  <main>
+    <div class="content default">
+      <ul>
+        <li>A Paragraph</li>
+        <li>Another Paragraph</li>
+      </ul>
+    </div>
+  </main>
+  <footer>
+    <div class="content footer">
+      <p>Here's some contact info</p>
+    </div>
+  </footer>
+</div>
+```
+
+请注意：
+
+1. 和 Vue 本身提供的 slot 机制不太相同，每个 Content 分发的内容都会被一个 div 所包裹，其 class 是 content 和 slot 的名字。
+2. 请确保所定义的 slot 的唯一性。

Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ module.exports = {`
`42`	`42`	`lastUpdated: 'Last Updated',`
`43`	`43`	`nav: require('./nav/en'),`
`44`	`44`	`sidebar: {`
`45`		`- '/guide/': genSidebarConfig('Guide')`
	`45`	`+ '/guide/': genSidebarConfig('Guide', 'Advanced')`
`46`	`46`	`}`
`47`	`47`	`},`
`48`	`48`	`'/zh/': {`
`@@ -52,7 +52,7 @@ module.exports = {`
`52`	`52`	`lastUpdated: '上次更新',`
`53`	`53`	`nav: require('./nav/zh'),`
`54`	`54`	`sidebar: {`
`55`		`- '/zh/guide/': genSidebarConfig('指南')`
	`55`	`+ '/zh/guide/': genSidebarConfig('指南', '深入')`
`56`	`56`	`}`
`57`	`57`	`}`
`58`	`58`	`}`
`@@ -71,22 +71,29 @@ module.exports = {`
`71`	`71`	`clientRootMixin: path.resolve(__dirname, 'mixin.js')`
`72`	`72`	`}`
`73`	`73`
`74`		`-function genSidebarConfig (title) {`
	`74`	`+function genSidebarConfig (gruopA, groupB) {`
`75`	`75`	`return [`
`76`	`76`	`{`
`77`		`- title,`
	`77`	`+ title: gruopA,`
`78`	`78`	`collapsable: false,`
`79`	`79`	`children: [`
`80`	`80`	`'',`
`81`	`81`	`'getting-started',`
`82`	`82`	`'directory-structure',`
`83`		`- 'permalinks',`
`84`	`83`	`'basic-config',`
`85`	`84`	`'assets',`
`86`	`85`	`'markdown',`
`87`	`86`	`'using-vue',`
`88`	`87`	`'i18n',`
`89`		`- 'deploy'`
	`88`	`+ 'deploy',`
	`89`	`+ ]`
	`90`	`+ },`
	`91`	`+ {`
	`92`	`+ title: groupB,`
	`93`	`+ collapsable: false,`
	`94`	`+ children: [`
	`95`	`+ 'permalinks',`
	`96`	`+ 'markdown-slot'`
`90`	`97`	`]`
`91`	`98`	`}`
`92`	`99`	`]`