feat: support using content excerpt as summary (close #82)

docs/README.md

@@ -137,6 +137,14 @@ location: Taipei
 ---
 ```
 
+### Summary
+
+By default, summary will be extracted from source markdowns. If you need to override it, we present the following two approaches:
+
+1. [Writing the summary manually in frontmatter](./front-matter.md#summary)
+
+2. [Setting up excerpt separator by writing a comment `<!-- more -->` right below what you want to extract as summary](https://vuepress.vuejs.org/theme/writing-a-theme.html#content-excerpt)
+
 ## Quick Start
 
 To make it easier to get started, you can use [create-vuepress](https://github.com/vuepressjs/create-vuepress) which is indeed an npm package, but it doesn’t mean you need to install it manually first. Here's an example:

example/_posts/2018-11-7-frontmatter-in-vuepress.md

@@ -10,6 +10,8 @@ location: Hangzhou
 
 Any markdown file that contains a YAML front matter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The front matter must be the first thing in the markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
 
+<!-- more -->
+
 ```markdown
 ---
 title: Blogging Like a Hacker

example/_posts/2019-2-26-markdown-slot.md

@@ -10,6 +10,8 @@ location: Hangzhou
 
 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.
 
+<!-- more -->
+
 ## Why do I need Markdown Slot?
 
 First, let's review the relationship between layout components and markdown files:

example/_posts/2019-5-6-writing-a-vuepress-theme-2.md

@@ -168,10 +168,6 @@ Finally, don't forget that `this.$route` and `this.$router` are also available a
   `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated).
 :::
 
-## Content Excerpt
-
-If a markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
-
 ## App Level Enhancements
 
 Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:

example/_posts/2019-5-6-writing-a-vuepress-theme-3.md

@@ -168,10 +168,6 @@ Finally, don't forget that `this.$route` and `this.$router` are also available a
   `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated).
 :::
 
-## Content Excerpt
-
-If a markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
-
 ## App Level Enhancements
 
 Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:

example/_posts/2019-5-6-writing-a-vuepress-theme-4.md

@@ -168,10 +168,6 @@ Finally, don't forget that `this.$route` and `this.$router` are also available a
   `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated).
 :::
 
-## Content Excerpt
-
-If a markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
-
 ## App Level Enhancements
 
 Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:

example/_posts/2019-5-6-writing-a-vuepress-theme.md

@@ -20,6 +20,8 @@ To write a theme, create a `.vuepress/theme` directory in your docs root, and th
 
 From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme.
 
+<!-- more -->
+
 ## Content Outlet
 
 The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content:
@@ -168,10 +170,6 @@ Finally, don't forget that `this.$route` and `this.$router` are also available a
   `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated).
 :::
 
-## Content Excerpt
-
-If a markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
-
 ## App Level Enhancements
 
 Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:

global-components/BaseListLayout.vue

@@ -14,10 +14,16 @@
         <header class="ui-post-title" itemprop="name headline">
           <NavLink :link="page.path">{{ page.title }}</NavLink>
         </header>
-
-        <p class="ui-post-summary" itemprop="description">
+        <!-- eslint-disable vue/no-v-html -->
+        <p
+          v-if="page.excerpt"
+          class="ui-post-summary"
+          itemprop="description"
+          v-html="page.excerpt"
+        />
+        <!-- eslint-enable vue/no-v-html -->
+        <p v-else class="ui-post-summary" itemprop="description">
           {{ page.frontmatter.summary || page.summary }}
-          <!-- <Content :page-key="page.key" slot-key="intro"/>-->
         </p>
 
         <footer>