vuepress-plugin-contributors
This component allows you to add a list of all contributors, which is sorted descending by the number of contributions.
To get the list of contributors this plugins uses git shortlog -nse --no-merges HEAD
. The shortlog is taken from the root path of the project, if you want the contributors to be retrieved only from a certain path, you can specify it with parameter baseDir
. If you expect double entries due to e.g. changes of email-adresses, you may specify a .mailmap
in the root of your project. (See git dcumentation)
Installation
$ npm install vuepress-plugin-contributors --save # or, if you prefer yarn $ yarn add vuepress-plugin-contributors
After installing, add it to your Vuepress configuration's plugin list:
moduleexports = plugins: 'vuepress-plugin-contributors'
Usage
Just put the following code somewhere in one of your markdown files:
<contributors />
Options
This plugin takes a number of options, which can be passed in n options object:
moduleexports = plugins 'vuepress-plugin-contributors' showAvatar: true showCount: true avatarSize: 32 defaultAvatar: '/not-found.png' avatarProvider: 'github' userProfileUrlProvider: 'github'
showAvatar
- Type:
Boolean
- Default:
false
If set to true
an avatarProvider has to be specified to show the avatars.
avatarProvider
- Type:
String|function
- Default:
undefinded
Following avatar sources are supported: github
, gitlab
or gravatar
. In case of gitlab
the email address of the user has to public to enable the plugin to fetch the avatar url.
You can specify a function in case you would like to use a different avatar source or your documentation is running on premise and you need a different url for the standard avatar-providers. This function is called with 2 parameters:
- user:
Object
, contains two fieldsname
(String) andemail
(String) - avatarSize:
Integer
Size of the avatar in pixel.
Expected return value: String
The url to the avatar.
Sample:
const rp = ; 'vuepress-plugin-contributors' avatarProvider: async { var options = strictSSL: false json: true ; optionsuri = `https://<your.gitlab.server>/api/v4/avatar?email=&size=`; var json = await ; return jsonavatar_url; } avatarSize: 32 defaultAvatar: '/transparent.png'
defaultAvatar
- Type:
String
- Default:
undefined
Path to a default avatar, when no avatar is found in the source. This file must be in the public folder of .vuepress
to ensure the name isn't changed during webpack.
avatarSize
- Type:
Integer
- Default:
32
The size of the avatars. This value is provided to the avatarProvider
function, if specified.
showCount
- Type:
Boolean
- Default:
false
Should the number of commits be shown in brackets behind the name.
userProfileUrlProvider
- Type:
String|function
- Default:
undefinded
Following user profile sources are supported: github
or gitlab
. In these cases the user profile url is built by adding user.name to the url.
You can specify a function in case you would like to use a different user profile source:
- user:
Object
, contains two fieldsname
(String) andemail
(String)
Expected return value: String
The url to the user profile.
Sample:
'vuepress-plugin-contributors' userProfileUrlProvider: async { return `http://your-server.domain/user/`; }
baseDir
- Type:
String
- Default:
''
Specifies the path from where the contributors should be taken. If you have your documentation within a source-code project (e.g. in the docs folder) and you only want to list the contributors for the documentation, then value of baseDir
has to be docs
.