From 12c2beb7a5e01a155e34e0f157de1bca1215213f Mon Sep 17 00:00:00 2001
From: ULIVZ <472590061@qq.com>
Date: Wed, 8 Aug 2018 23:17:08 +0800
Subject: [PATCH] docs: docuement using components in headers

---
 docs/guide/using-vue.md    | 20 ++++++++++++++++++++
 docs/zh/guide/using-vue.md | 18 ++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md
index dd83d3fd03..47cc8bab02 100644
--- a/docs/guide/using-vue.md
+++ b/docs/guide/using-vue.md
@@ -126,6 +126,22 @@ Inside any markdown file you can then directly use the components (names are inf
 Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
 :::
 
+### Using Components In Headers
+
+You can use Vue components in the headers, but note the difference between the following two ways:
+
+| markdown | Output HTML | Parsed Header |
+|--------|-------------|----------------|
+| <pre v-pre><code> # text &lt;Tag/&gt; </code></pre> | `<h1>text <Tag/></h1>` | `text` |
+| <pre v-pre><code> # text \`&lt;Tag/&gt;\` </code></pre> | `<h1>text <code>&lt;Tag/&gt;</code></h1>` | `text <Tag/>` |
+
+The HTML wrapped by `<code>` will be displayed as is, only the HTML that is not wrapped will be parsed by Vue.
+
+::: tip
+
+The output HTML is accomplish by [markdown-it](https://github.com/markdown-it/markdown-it), while the parsed header is done by VuePress, and used for the [sidebar](../default-theme-config/README.md#sidebar) and the document title.
+:::
+
 ## Using Pre-processors
 
 VuePress has built-in webpack config for the following pre-processors: `sass`, `scss`, `less`, `stylus` and `pug`. All you need to do is installing the corresponding dependencies. For example, to enable `sass`, install the following in your project:
@@ -220,3 +236,7 @@ You can use this component in header to add some status for some API:
 ``` md
 ### Badge <Badge text="beta" type="warn"/> <Badge text="0.10.1+"/>
 ```   
+
+**Also see:** 
+
+- [Using Components In Headers](#using-components-in-headers)
diff --git a/docs/zh/guide/using-vue.md b/docs/zh/guide/using-vue.md
index 2a248291e6..abf7be60f1 100644
--- a/docs/zh/guide/using-vue.md
+++ b/docs/zh/guide/using-vue.md
@@ -126,6 +126,20 @@ export default {
 请确保一个自定义组件的名字包含连接符或者是 PascalCase，否则，它将会被视为一个内联元素，并被包裹在一个 `<p>` 标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定， `<p>` 标签中不允许放置任何块级元素。
 :::
 
+### 在标题中使用组件
+
+你可以在标题中使用 Vue 组件，但是请留意以下两种方式的不同：
+
+| Markdown | 输出的 HTML | 解析后的标题 |
+|--------|-------------|----------------|
+| <pre v-pre><code> # text &lt;Tag/&gt; </code></pre> | `<h1>text <Tag/></h1>` | `text` |
+| <pre v-pre><code> # text \`&lt;Tag/&gt;\` </code></pre> | `<h1>text <code>&lt;Tag/&gt;</code></h1>` | `text <Tag/>` |
+
+被 `<code>` 包装的 HTML 将按原样显示，只有未被包装的 HTML 才会被 Vue 解析。
+
+::: tip
+输出的 HTML 由 [markdown-it](https://github.com/markdown-it/markdown-it) 完成。而解析后的标题由 VuePress 完成，用于[侧边栏](../default-theme-config/README.md#侧边栏)以及文档的标题。
+:::
 
 ## 使用预处理器
 
@@ -223,3 +237,7 @@ export default {
 ``` md
 ### Badge <Badge text="beta" type="warn"/> <Badge text="0.10.1+"/>
 ```  
+
+**参考:** 
+
+- [在标题中使用组件](#在标题中使用组件)