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.
Edit