介绍

2019/9/30

# 插件是什么

VuePress 自 1.0 版本开始对插件进行了支持,这使得我们不仅可以应用一个喜欢的主题,而且可以自己去选择一些插件来丰富你的博客或者文档内容,搭建一个属于你自己的静态网站。

主题也自 vuepress-theme-reco@1.1.0 版本开始进行插件化,将能够独立的功能或组件封装成插件,精简核心代码,方便维护和扩展。

# 插件的来源有哪些

# vuepress-reco 组织下的插件

我们开发了一些能够帮助你丰富网站内容的小插件,你可以根据自己的喜好去启用它们。

我们的插件均发布在 npm 的组织 vuepress-reco 下,所以以下插件默认全称为 @vuepress-reco/vuepress-plugin-<name> (比如 back-to-top 的完整名称为 @vuepress-reco/vuepress-plugin-back-to-top) ,下面将简写组织内插件名称。

名称 版本 是否内置 是否主题独占 描述
back-to-top npm 返回顶部插件
pagation npm 分页插件,帮助你快速跳转到任意页面
screenfull npm 全屏按钮插件
loading-page npm 页面加载时过渡动画插件
kan-ban-niang npm 看板娘插件,为你的网站添加一个萌萌哒看板娘~
comments npm 评论插件,集成了 Valine 与 Vssue 两种评论系统
extract-code npm 代码展示插件,可以方便地帮你展示多种代码组合
rss npm RSS 生成插件
bgm-player npm 背景音乐播放器

注意

  • 只有内置插件是在安装主题时安装并配置好的,非内置插件(比如 kan-ban-niang 插件)需要你自行安装并配置。
  • 为了使得主题更加定制化,我们开发了一些本主题独占的插件(比如 rss 插件),由于和主题之间存在强耦合,所以这些插件在其他主题可能不会正常工作

# npm 中的 VuePress 插件生态

如果你想额外添加一些自己喜欢的插件,你可以在 npm 中搜索 vuepress-plugin (opens new window) 前缀来查看当前 VuePress 社区中已经开发的插件,之后使用 npm 或者 yarn 下载并在 .vuepress/config.js配置以启用它们。

# 主题内置插件

主题内置了一些适合于博客以及文档开箱即用的插件,方便你更快地搭建起一个简洁而又不失优雅的静态网站。

这些内置的插件已经按照主题风格进行配置,你不需要去手动去启用它们,但如果你不喜欢我们内置的配置,完全可以修改插件配置甚至禁用插件。

名称 是否必需 默认配置 描述
back-to-top - ...
comments 需主题配置内配置 $themeConfig.vssueConfig 或者 $themeConfig.valineConfig ...
loading-page 作为组件,无需配置 ...
pagation 作为组件,无需配置 ...
screenfull 作为组件,无需配置 ...
extractCode - ...
@vuepress/plugin-active-header-links (opens new window) - 页面滚动时自动激活侧边栏链接插件
@vuepress/plugin-medium-zoom (opens new window) {selector: '.theme-reco-content :not(a) > img'} 图片缩放插件
@vuepress/plugin-nprogress (opens new window) - 一个基于 nprogress 的进度条插件
@vuepress/plugin-search (opens new window) - 基于 Headers 的搜索插件
@vuepress/plugin-blog (opens new window) 本插件是博客系统的基础,请不要禁用或者覆盖配置 博客插件
vuepress-plugin-container (opens new window) 使用默认主题的配置,效果见在 Markdown 中使用容器 在你的文档中注册新的 Markdown 容器,可同时注册多个容器

什么是必需插件

因为主题正处于插件化的进程中,与大部分插件尚存在一些耦合,如果你通过手动禁用这些插件可能会引发某些莫名其妙的错误,所以请尽量不要禁用标有必需标志的插件,如果你有这样的需求,欢迎在评论中留言

# 插件怎么用

关于插件的使用的详细文档 (opens new window)

# 插件的下载

如果你有一个已经发布在 npm 的喜欢的插件,你可以使用以下命令来下载并安装它

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

注意

这里的包名需要全称,并不能省略 vuepress-plugin-

# 简单使用插件

在下载插件后,你可以通过在 .vuepress/config.js 中做一些配置来使用插件

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

你甚至可以省略掉 vuepress-plugin-

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

# 为插件配置选项

如果你选择的插件支持 Options ,那么你可以通过以下两种方式添加

# 1. Babel 式

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

就像这样

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. 对象式

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

你可以通过这种方式来对主题内置插件的配置进行覆盖,甚至禁用一个内置插件

只需将 Options 设置成 false 便可禁用该插件

就像这样

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