diff --git a/docs/guide/custom-themes.md b/docs/guide/custom-themes.md index c2f75cec45..75aeaefc8d 100644 --- a/docs/guide/custom-themes.md +++ b/docs/guide/custom-themes.md @@ -66,6 +66,20 @@ The compiled content of the current `.md` file being rendered will be available ``` +## Theme Level Enhancements + +Themes can extend the Vue app that VuePress uses by exposing an `index.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: + +``` js +export default ({ + Vue, // the version of Vue being used in the VuePress app + options, // the options for the root Vue instance + router // the router instance for the app +}) => { + // ...apply enhancements to the app +} +``` + ## Using Theme from a Dependency Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`. diff --git a/lib/app/app.js b/lib/app/app.js index 4db19c1acc..1b7f708017 100644 --- a/lib/app/app.js +++ b/lib/app/app.js @@ -7,6 +7,7 @@ import NotFound from '@notFound' import { routes } from '@temp/routes' import { siteData } from '@temp/siteData' import enhanceApp from '@temp/enhanceApp' +import themeEnhanceApp from '@temp/themeEnhanceApp' // suggest dev server restart on base change if (module.hot) { @@ -75,7 +76,8 @@ export function createApp () { }) const options = {} - + + themeEnhanceApp({ Vue, options, router }) enhanceApp({ Vue, options, router }) const app = new Vue( diff --git a/lib/prepare.js b/lib/prepare.js index bb74626ad1..1f86c2e2f1 100644 --- a/lib/prepare.js +++ b/lib/prepare.js @@ -53,15 +53,21 @@ if (!Object.assign) Object.assign = require('object-assign')` await writeTemp(`override.styl`, hasUserOverride ? `@import(${JSON.stringify(overridePath)})` : ``) } + async function writeEnhanceTemp (destName, srcPath, isEnhanceExist) { + await writeTemp( + destName, + isEnhanceExist + ? `export { default } from ${JSON.stringify(srcPath)}` + : `export default function () {}` + ) + } + // 6. handle enhanceApp.js - const enhancePath = path.resolve(sourceDir, '.vuepress/enhanceApp.js') - const hasEnhancePath = fs.existsSync(enhancePath) - await writeTemp( - 'enhanceApp.js', - hasEnhancePath - ? `export { default } from ${JSON.stringify(enhancePath)}` - : `export default function () {}` - ) + const enhanceAppPath = path.resolve(sourceDir, '.vuepress/enhanceApp.js') + writeEnhanceTemp('enhanceApp.js', enhanceAppPath, fs.existsSync(enhanceAppPath)) + + // 7. handle the theme index.js + writeEnhanceTemp('themeEnhanceApp.js', options.themeApp, fs.existsSync(options.themeApp)) return options } @@ -153,6 +159,11 @@ async function resolveOptions (sourceDir) { } else { options.notFoundPath = path.resolve(__dirname, 'default-theme/NotFound.vue') } + + const themeApp = path.resolve(themeDir, 'index.js') + if (fs.existsSync(themeApp)) { + options.themeApp = themeApp + } } // resolve pages