Feature: theme-related pages

docs/zh/guide/custom-themes.md

@@ -85,6 +85,24 @@ export default ({
 }
 ```
 
+## 渲染主题页面
+
+自定义主题可以通过主题根目录下的 `pages.js` 文件使 VuePress 渲染属于主题的页面。这个文件应当 `export default` 一个异步函数，并接受一个包含了站点元数据等属性的对象作为参数。该函数需要返回一个数组，数组内容为需要渲染的页面元数据。你可以在这个文件中定义主题所需渲染的页面，例如：为博客系统设计的归档页面、分类页面等。
+
+另外，你需要结合[应用配置](#应用配置)一节中的说明，注册合适的应用路由。否则，渲染结果只会是一些 404 页面。
+
+::: tip 
+该模块被 webpack 直接引用，因此你可能需要使用 CommonJS 语法来导出函数。
+:::
+
+```js
+exports.default = async function ({ siteData }) {
+  return [
+    { path: '/archive.html' } // path 定义渲染目标，它和其它元数据一起将被放在 $page 里。
+  ]
+}
+```
+
 ## 使用来自 npm 的主题
 
 主题可以以 Vue 单文件组件的格式，并以 `vuepress-theme-xxx` 的名称发布到 npm 上。

lib/prepare.js

@@ -33,6 +33,8 @@ module.exports = async function prepare (sourceDir) {
   ].join('\n\n'))
 
   // 3. generate siteData
+  const themePages = await resolveThemePages(options)
+  options.siteData.pages = options.siteData.pages.concat(themePages)
   const dataCode = `export const siteData = ${JSON.stringify(options.siteData, null, 2)}`
   await writeTemp('siteData.js', dataCode)
 
@@ -178,6 +180,11 @@ async function resolveOptions (sourceDir) {
     if (fs.existsSync(themeEnhanceAppPath)) {
       options.themeEnhanceAppPath = themeEnhanceAppPath
     }
+
+    const themePagesPath = path.resolve(themeDir, 'pages.js')
+    if (fs.existsSync(themePagesPath)) {
+      options.themePagesPath = themePagesPath
+    }
   }
 
   // resolve pages
@@ -224,6 +231,17 @@ async function resolveOptions (sourceDir) {
   return options
 }
 
+async function resolveThemePages ({ themePagesPath, siteData }) {
+  // render theme pages
+  if (themePagesPath) {
+    const pages = await require(themePagesPath).default({
+      siteData: siteData
+    })
+    return pages
+  }
+  return []
+}
+
 async function genComponentRegistrationFile ({ sourceDir }) {
   function genImport (file) {
     const name = fileToComponentName(file)