Comment Plugin

Vssue Config

Mr.Hope ... 2020-5-7 About 4 min

# platform

@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
  • Platform gitea - API package @vssue/api-gitea-v1

# owner

  • Type: string

  • Details:

    The owner’s name of repository to store the issues and comments. Could be the name of a user or an organization (GitHub Organization / Gitlab Group / Bitbucket Team).

    Together with repo, Vssue could locate the repository on the platform.

  • Reference: repo

# repo

  • Type: string

  • Details:

    The name of repository to store the issues and comments.

    Together with owner, Vssue could locate the repository on the platform.

  • Reference: owner

Tips

The common pattern of repository’s URL is `${baseURL}/${owner}/${repo}`:

  • GitHub: https://github.com/${owner}/${repo}
  • Gitlab: https://gitlab.com/${owner}/${repo}
  • Bitbucket: https://bitbucket.org/${owner}/${repo}
  • Gitee: https://gitee.com/${owner}/${repo}

# clientId

  • Type: string

  • Details:

    The client_id introduced in OAuth2 spec (opens new window).

    It’s the client identifier that issued by the platform. You will get it after you set up OAuth App.

    Vssue will use it to get user’s access token.

  • Reference:

# clientSecret

  • Type: string

  • Default: undefined

  • Details:

    The client_secret introduced in OAuth2 spec (opens new window).

    It’s the client secret that generated by the platform. You will get it after you set up OAuth App.

    When work with some of the platforms, Vssue will use it together with clientId to get user’s access token.

    Tips

    Some platforms (for example Bitbucket and GitLab) support Implicit Grant (opens new window), so we don’t need clientSecret for those platforms. Mean while, some platforms (for example GitHub and Gitee) do not support it now, so clientSecret is required for those platforms.

  • Reference:

# baseURL

  • Type: string

  • Default: undefined (according to the platform)

  • Details:

    This is the base URL of your platform.

    Default values for supported platforms are:

    • 'https://github.com' for GitHub
    • 'https://gitlab.com' for Gitlab
    • 'https://bitbucket.org' for Bitbucket
    • 'https://gitee.com' for Gitee

    Note

    Only when you choose to use self-hosted platform should you set this option. (for example GitLab Community / Enterprise Edition or GitHub Enterprise Server)

  • Reference:

# state

  • Type: string

  • Default: 'Vssue'

  • Details:

    The state element introduced in OAuth2 spec (opens new window).

    Vssue will send it with OAuth redirection and check whether matched in callback.

    It’s designed for preventing CSRF (opens new window), but it’s not so useful here as we put everything in a static page, you can ignore it or set it to anything you like.

# labels

  • Type: string

  • Default: ['Vssue']

  • Details:

    To set the labels of issues that Vssue uses.

    Vssue will only request those issues with the labels and ignore others. Together with title, labels will help to identify the corresponding issue of Vssue. If you use multiple labels by setting more strings, only issues with all those labels will be requested by Vssue.

    Tips

    Bitbucket does not support issue labels for now, so this option will be ignored if you are using Bitbucket.

    GitHub supports emoji in labels’ name, for example [':heart:Vssue', ':mailbox:Comments'].

  • Reference: title

# prefix

  • Type: string

  • Default: '[Vssue]'

  • Details:

    The title prefix for issues. Used for generating the actual title of the corresponding issue.

    For example, if the prefix is '[Vssue]' and the title is 'Vssue Demo', the actual title of the corresponding issue is '[Vssue]Vssue Demo'.

    It will be ignored if the type of title is Function.

  • Reference: title

# admins

  • Type: string[]

  • Default: []

  • Details:

    Array of username that has admin access to Vssue. The owner always has admin access.

    Users with admin access can delete all comments, while other users can only delete their own comments.

    Only admins can auto create corresponding issue if it does not exist.

    Tips

    To auto create the issue when the owner is a organization rather than a user, you can add your username into admins.

  • Reference: owner

# perPage

  • Type: number

  • Default: 10

  • Details:

    The default value of comments to show per page.

# locale

  • Type: string

  • Default: undefined

  • Details:

    The locale language.

    If not set, Vssue will use one of window.navigator.languages, or fallback to 'en'.

    Tips

    Vssue uses vue-i18n (opens new window) for i18n, but it will not affect other parts of your Vue App. And if you already have vue-i18n in your project, it will not affect Vssue.

    Language packages locate in src/i18n/langs (opens new window) directory. We have supported:

    • 'en' ('en-US')
    • 'zh' ('zh-CN')
    • 'pt' ('pt-BR')
    • 'ja' ('ja-JP')

    Contributions welcome for more languages support.

# proxy

  • Type: string | ((url: string) => string)

  • Default: url => `https://cors-anywhere.herokuapp.com/${url}`

  • Details:

    Some platforms (for example GitHub and Gitee) do not support Implicit Grant, so we have to request the API of the platform to get the access token.

    However, the access token API of the platforms do not support CORS (see related issue of GitHub (opens new window)). As Vssue is a pure frontend plugin, we have to use a proxy to request access token.

    By default, we use an open source CORS proxy service cors-anywhere (opens new window) for that.

    To use your own proxy, you need to set this option.

    If the platform you use does not require clientSecret, this option will be ignored.

  • Example:

    proxy: (url) => `https://your.cors.porxy?target=${url}`;
    1

  • Reference:

# issueContent

  • Type: ((param: { options: Vssue.Options, url: string }) => string | Promise<string>)

  • Default: ({ url }) => url

  • Details:

    The content of issue that auto created by Vssue.

    Vssue will use the return value of the function as the content.

    The parameter includes two properties:

    • options is the options of Vssue.
    • url is the URL of current page.

  • Example:

    issueContent: ({ url }) =>
  `This issue is auto created by Vssue to store comments of this page: ${url}`;
    1
    2

    Tips

    The issueContent option is only used to auto create the corresponding issue when it does not exist.

    If the issue already exists, Vssue will not try to update the content.

# autoCreateIssue

  • Type: boolean

  • Default: false

  • Details:

    If autoCreateIssue is set to true, Vssue will try to create an issue automatically when the corresponding issue does not exist. Notice that if you have not logged-in, Vssue will redirect to the authorization page automatically.

    If autoCreateIssue is set to false, you need to create the issue manually.

Edit this page
Last update: May 16, 2021 15:14
Contributors: Mr.Hope