Using Vssue

Mr.Hope ... About 2 min

# Using Vssue

# Choose a platform to use

Vssue can enable comments for your static pages via the Issue System of Github, Gitlab, Bitbucket or Gitee, and you can choose one of those platforms.

Go to Supported Platforms - Set up OAuth App for detailed instructions.

After this step, you will get client id and client secret of your OAuth App, which will be used for Vssue options:

  • owner: the account / group that owns the repository
  • repo: the name of the repository to store comments
  • clientId: the client id of your oauth app
  • clientSecret: the client secret of your oauth app (only required for some of the platforms)

# Vssue Config

This plugin uses @vssue/vuepress-plugin-vssue (opens new window) to help use Vssue in VuePress.

# Use the plugin

// .vuepress/config.js

module.exports = {
  plugins: {
    "@mr-hope/comment": {
      type: "vssue",
      // set `platform` rather than `api`
      platform: "github",

      // all other options of Vssue are allowed
      owner: "OWNER_OF_REPO",
      repo: "NAME_OF_REPO",
      clientId: "YOUR_CLIENT_ID",
      clientSecret: "YOUR_CLIENT_SECRET",
    },
  },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Tips

The only difference is that, you should set platform rather than the api package itself.

@vssue/vuepress-plugin-vssue will auto resolve the corresponding API package according to the value of platform:

  • Platform github - API package @vssue/api-github-v3
  • Platform github-v4 - API package @vssue/api-github-v4
  • Platform gitlab - API package @vssue/api-gitlab-v4
  • Platform bitbucket - API package @vssue/api-bitbucket-v2
  • Platform gitee - API package @vssue/api-gitee-v5

# Use Vssue Component

Vssue has already been registered as a Vue component, and can be used in your VuePress Markdown directly.

<!-- README.md -->

# Vssue Demo

<Vssue title="Vssue Demo" />
1
2
3
4
5

Tips

You can go to the repository meteorlxy/vssue-demo (opens new window) to get the demo code.

# Custom Style Variables

With the power of palette.styl (opens new window) of VuePress, you can set the Vssue Style.

There are some predefined Stylus variables (opens new window) of Vssue, and you can check them in vssue/src/styles/_variables.styl:

// the main color
$vssue-theme-color

// the text color (used for common text)
$vssue-text-color

// the text light color (used for muted text, disabled text, etc)
$vssue-text-light-color

// the border color
$vssue-border-color

// the progress color
$vssue-progress-color

// the font size
$vssue-font-size

// the font family
$vssue-font-family

// the mobile breakpoint
$vssue-breakpoint-mobile

// the text direction (ltr / rtl) (used for RTL languages, e.g. Hebrew)
$vssue-direction
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

For example, Vssue use a "Vue green" (#3eaf7c) as the theme color, which is defined as the default value of variable $vssue-theme-color. You can change the theme color by setting $vssue-theme-color before import vssue/src/styles/index.styl.

By default, those Vssue variables are set to VuePress variables:

// @vssue/vuepress-plugin-vssue/styles/index.styl

$vssue-theme-color ?= $accentColor
$vssue-text-color ?= $textColor
$vssue-border-color ?= $borderColor
$vssue-breakpoint-mobile ?= $MQMobile
1
2
3
4
5
6

To override them, just set them in your palette.styl:

// .vuepress/styles/palette.styl

$vssue-theme-color = red
1
2
3

# Do not want to use our plugin

Vssue has tried to be SSR-friendly, so you can import Vssue directly in VuePress like other vue plugins / components without @vssue/vuepress-plugin-vssue (especially if you have customized the styles of Vssue).

But we still suggest you to use @vssue/vuepress-plugin-vssue in VuePress, which has already helped you make <Vssue> component client-only to avoid some potential issues.

If you do not want to use the plugin we provided, you may need to wrap <Vssue> component into <ClientOnly> component to avoid those potential issues, that is :

<ClientOnly>
  <Vssue />
</ClientOnly>
1
2
3

See Built-in Components - ClientOnly (opens new window) of VuePress