vuepress-theme-reco

Introduction to Plugins

9/30/2019

# What is Plugin

Since version 1.0 VuePress supported plugins, which not only enable us to use our favorite theme but also choose some plugins to enrich your blog or domentation and build your own static website.

Our theme vuepress-theme-reco has also become a plugin since version 1.1.0. We packed independent features or components into plugins, which make our core code simpler and easier to maintain and extend.

# Source of Plugins

# Plugins under vuepress-reco

We developed some plugins to help enrich your website. You could choose to use them if you wish.

The plugins we developed are under npm's organization vuepress-reco, so the default full name of a following plugin is @vuepress-reco/vuepress-plugin-<name> (such as the full name for back-to-top is @vuepress-reco/vuepress-plugin-back-to-top). We will just list the short names below.

Name Version Built-in? Can Only Be Used in Our Theme? Description
back-to-top npm ✔ ✖ Go back to top of the page
pagation npm ✔ ✖ Paginate your posts and quickly navigate to any page
screenfull npm ✔ ✖ Bring the page or any element into full screen
loading-page npm ✔ ✖ Show animation when loading pages
kan-ban-niang npm ✖ ✖ Add a cute kanban girl
comments npm ✔ ✖ Comment plugin to support 2 comment systems: Valine and Vssue
extract-code npm ✔ ✖ Display code of multiple languages
rss npm ✖ ✔ Help generate RSS
bgm-player npm ✖ ✖ Add a bgm player

Note

  • only built-in plugins are customized when installing our theme, non built-in ones require you to install and customize yourself
  • to make the theme more customized, we developed some plugins only suited for our theme (such as the RSS one). Thus, these plugins might not work in other themes

# VuePress Plugin Ecosystem in npm

If you want to add some of your favorite plugins, you could search vuepress-plugin in npm (opens new window). Then use npm or yarn to download plugins and add them in .vuepress/config.js to start using.

# Built-in Plugins in Our Theme

We have some out-of-the-box built-in plugins in our theme to help you quickly build a simple and elegant static website.

These built-in plugins have already been customized according to the style of our theme and you don't need to trigger manually. If you don't like our default customizations, you are free to change customizations yourself or simply disable them.

Name Must-have? Default Settings 描述
back-to-top ✖ - ...
comments ✔ Need to add $themeConfig.vssueConfig or $themeConfig.valineConfig ...
loading-page ✔ No customization needed ...
pagation ✔ No customization needed ...
screenfull ✔ No customization needed ...
extractCode ✖ - ...
@vuepress/plugin-active-header-links (opens new window) ✖ - Automatically activates sidebar links when page scrolls
@vuepress/plugin-medium-zoom (opens new window) ✖ {selector: '.theme-reco-content :not(a) > img'} medium-zoom (opens new window) plugin
@vuepress/plugin-nprogress (opens new window) ✖ - A progress bar plugin based on nprogress (opens new window)
@vuepress/plugin-search (opens new window) ✔ - A search plugin based on Headers (opens new window)
@vuepress/plugin-blog (opens new window) ✖ This is a basic plugin for blogging. Please don't disable or change config A plugin for blogging
vuepress-plugin-container (opens new window) ✖ Use the default theme config, see demo at Use Containers in Markdown Register (multiple) new containers in your articles

What is a must-have plugin?

Since our theme is transforming to plugins and still haven't decoupled from most plugins, you might encounter weird errors if disabling them. Thus, please don't disable the must-have ones. If you have such needs, please comment below.

# How to Use a Plugin

Detailed documentation on how to use a plugin (opens new window)

# Download a Plugin

If you like a released plugin in npm, you could execute the following commands to download and install it:

yarn add <pagkageName> -D
# or
npm i <packageName> -D

Note

A full package name is needed, i.e., have to prepend vuepress-plugin-

# Use a Plugin

After downloading a plugin, you could customize your .vuepress/config.js to use it:

module.exports = {
  plugins: ["vuepress-plugin-xxx"]
};

You could omit vuepress-plugin-:

module.exports = {
  plugins: ["xxx"]
};

# Customize a Plugin

If your chosen plugin supports options, you could customize in two ways:

# 1. Babel-like

module.exports = {
  plugins: [
    [
      "vuepress-plugin-xxx",
      {
        /* options */
      }
    ]
  ]
};

such as:

module.exports = {
  plugins: [
    [
      "@vuepress-reco/vuepress-plugin-kan-ban-niang",
      {
        theme: ["miku"],
        clean: true,
        modelStyle: {
          position: "fixed",
          left: "0px",
          bottom: "0px",
          opacity: "0.9",
          zIndex: 99999
        }
      }
    ]
  ]
};

# 2. Object-oriented

module.exports = {
  plugins: {
    xxx: {
      /* options */
    }
  }
};

You could use this way to customize built-in plugins in our theme, or disable one by setting options to false:

module.exports = {
  plugins: [
    ["@vuepress-reco/back-to-top", false] // disabled.
  ]
};

Back to Top