Design Concepts of VuePress 1.x

    • Pluggable.
    • Convention over configuration.
    • Reasonable priority management.

    VuePress 1.0 has been rewritten extensively, and the most important one is the introduction of the Plugin API. What are the benefits of plugins?

    With plugins, we can implement many of the core functions with plugins, and you can see many built-in plugins that cover many of the core functions of VuePress, which used to blend in all parts of the code base, but now they’re clear at a glance.

    Configuration management

    In the past, when we came across some less common requirements, we had some doubts: if we wanted to not support it, VuePress usage scenarios were limited; but if we wanted to support it, we had to write it into the core code base and set up a separate configuration API for it. For the maintainers, apart from not conducive to long-term maintenance, this sometimes makes us feel exhausted. We must think of some better solutions. Yes, this is plugin.

    Yes, your configuration file is also a plugin, so you can use the Plugin API directly without having to create a new plugin for it and import it in the configuration.

    TIP

    The options supported by are actually based on the plugin options and add some specific options.

    theme/index.js is also a plugin

    The root configuration file of the theme is also a plugin.

    TIP

    In VuePress, you have the ability to apply some plugins in a plugin:

    VuePress 1.0 begin to introduce some conventions to reduce the user’s excessive configuration pressure, the most intuitive manifestation of this is the conventions for the document directory structure and the .

    In the future, we may combine community feedback to introduce more agreements. Let’s wait and see.

    Senior users have found that both theme developers and regular users have the ability to customize global palettes, styles, templates and plugins, so how do they work together?

    Loading Priority

    For templates/*, follow the certain loading priority. Taking templates/ssr.html as an example:

    Design Concepts - 图3

    Note

    When customizing templates/ssr.html, or templates/dev.html, it’s best to edit it on the basis of the , otherwise it may cause a build failure.

    palette.styl

    User’s styles/palette.styl has a higher priority than the theme’s styles/palette.styl, so the theme can define its own palette and the user can tweak it. For example:

    2. $accentColor = #0f0

    So the final value of $accentColor is #f00.

    index.styl

    Both the user’s styles/index.styl and the theme’s styles/index.styl are generated into the final CSS file, but the user’s style is generated later and therefore has higher priority. For example:

    1. // theme/styles/index.styl
    2. .content
    3.   font-size 14px

    The final generated CSS is as follows:

    1. /* theme/styles/index.styl */
    2. .content {
    3.   font-size: 14px;
    5. /* .vuepress/styles/index.styl */
    7.   font-size: 15px;
    8. }

    plugins

    Since all plugins with the same name can be applied ONLY once by default, users can override the default options for plugins in theme. For example:

    1. // .vuepress/config.js
    2. module.exports = {
    3.   plugins: [
    4.     'vuepress-plugin-xxx',
    5.     { name: 'bar' }
    6.   ]
    7. }

    Then the final value of name option will be bar.

    With the goal of decoupling, we were able to separate VuePress into the following two libraries by introducing monorepo:

    • ：The default theme you see now.

    Of course, for most users, you don’t need to worry about these three libraries. The VuePress package has already assembled them together, so you can use VuePress like 0.x.