Customizing the Default Vuepress Theme

Vuepress allows for “Theme Inheritance” to customizing an existing theme without ejecting the entire thing. The documentation is a bit confusing/sparse so here’s a quick reference:

• Create a .vuepress/theme directory and add an index.js to it containing the following. This tells Vuepress that the theme contained in .vuepress/theme extends the default theme.

  module.exports = {
    extend: '@vuepress/theme-default'
  }
  

• Override default theme components by copying files from node_modules/@vuepress/theme-default into .vuepress/theme, while maintaining the relative structure.
  • For example, node_modules/@vuepress/theme-default/components/Page.vue is copied to .vuepress/theme/components/Page.vue.
• Once that’s done, any references (import and require) in the file that was copied need to be fixed so they resolve to the original theme:

  Reference	Fix
  import	Change instances of @theme to @parent-theme In .vuepress/theme, @theme refers to itself and @parent-theme refers to the original.
  require	The @parent-theme doesn’t appear to work for requires. Simply copy over any required files into .vuepress/theme.

• At this point your site should build/load exactly as it did before you created .vuepress/theme.
• Edit the files you copied to .vuepress/theme to customize the theme.