VitePress Plugin to easily generate, update and display GitHub contributors. Automatically updated on every installation or deployment with custom options.
npm install @cssnr/vitepress-plugin-contributors
- Install
- Usage
- Options
- Demos
- Support
- Contributing
A VitePress Plugin to Easily generate, update and display repository Contributors.
This package includes two components that can be use together or individually.
1. get-contributors - script to generate the contributors.json file.
2. Contributors.vue - component to display the contributors in VitePress.
Also includes a detailed Installation guide with available Support.
> [!IMPORTANT]
> For Up-to-Date Documentation, please visit the website:
> https://vitepress-contributors.cssnr.com/
1. Install directly into your VitePress from npmjs.
``shell`
npm i @cssnr/vitepress-plugin-contributors
2. Add the get-contributors script to your package.json.
`json`
{
"scripts": {
"get-contributors": "npx get-contributors user/repo",
"postinstall": "npm run get-contributors"
}
}
_If you don't add the postinstall script you need to add get-contributors to your build._
Click Here to View Usage - get-contributors
Show help: npx get-contributors -h
Basic usage, all contributors excluding bot users.
`shell`
npx get-contributors user/repo
Limit to top 20 contributors, specify output file, and include bot users.
`shell`
npx get-contributors user/repo -m 20 -f .vitepress/contributors.json -b
Only the user/repo is required. All other arguments are optional.
| Argument Flag | Default Value | Description of the Argument |
| :----------------- | :----------------------------- | :----------------------------------------- |
| -f/--file | .vitepress/contributors.json | Output file relative to project root |-m
| /--max-users | 0 | Max users to fetch, 0 is unlimited |-b
| /--bots | - | Include bot users in the results |-e
| /--error | - | Throw errors during generation |-k
| /--keys | login,avatar_url | Contributor keys to save to file |
Note: This script makes 1 request to the GitHub API for every 100 contributors on the repository (or max-users).
Because of this if you have a lot of contributors (200+) running this back-to-back may hit
the GitHub rate limit for unauthenticated requests, which is 60 requests per hour.
If this occurs the script will generate a partial or empty contributors so development can continue.
This does not affect GitHub Action runs which are authenticated with the GTIHUB_TOKEN.
---
3. Add the contributors.json file location to your .gitignore.
`txt`
.vitepress/contributors.json
4. Generate the contributors.json file.
`shell`
npm run get-contributors
Alternatively, if you did not add the get-contributors script from step #2.
`shell`
npx get-contributors user/repo
5. Import the components in your .vitepress/theme/index.js.
`javascript
import DefaultTheme, { VPBadge } from 'vitepress/theme' // only if using VPBadge
import Contributors from '@cssnr/vitepress-plugin-contributors' // ADD this line
import '@cssnr/vitepress-plugin-contributors/style.css' // ADD this line
import contributors from '../contributors.json' // OPTIONAL - Global
export default {
...DefaultTheme,
enhanceApp({ app }) {
app.component('Badge', VPBadge) // only if using VPBadge
app.component('Contributors', Contributors) // ADD this line
app.config.globalProperties.$contributors = contributors // OPTIONAL - Global
},
}
`
Global - If you are unsure about this usage, add these lines for simplicity.
VPBadge - Only required if you are using the VitePress Badge.
More Details on the contributors.json path
Note, you may need to modify the ../contributors.json import location to match your setup..vitepress
If your VitePress configuration directory is located at then the default output.vitepress/contributors.json
path of will import from the relative path ../contributors.json.
If you are not importing contributors as a Global, this path will be relative to the file you are importing it in.
See the Usage for more details.
---
6. Finally, use the Contributors.vue component in your markdown or component.
`markdown`
See the Usage for more details...
To use, simply add the tag to your markdown file (or component).
If you added contributors as a global component, you only need the tag.
`markdown`
Otherwise, import the contributors.json and add a tag.
`markdown
`
The contributors.json file is relative to the file you are importing it in.
See the Options for more details...
Only the :contributors parameter is required, everything else is optional.
| Parameter | Default | Type | Description of the Parameter |
| :---------------- | :----------: | :----: | :----------------------------------------------------------------------------------------- |
| :contributors | Required | Array | contributors.json file import data |64
| max-users | - | String | Max Number of users to display |
| heading | - | String | Optional Heading text |
| size | | String | Size of Icons in pixels |
| margin | - | String | CSS margin string for container |
Example with all arguments.
`markdown``
heading="VitePress Contributors"
max-users="98"
size="48"
margin="36px 0 96px"
/>
The plugin is running on these pages:
- https://django-files.github.io/ and /team
- https://docker-deploy.cssnr.com/
- https://portainer-deploy.cssnr.com/
If you have a live demo, let us know and we will post it here...
Please let us know if you run into any issues
or want to see a new feature.
For general help or to request a feature:
- Q&A Discussion: discussions/q-a
- Request a Feature: discussions/feature-requests
If you are experiencing an issue/bug or getting unexpected results:
- Report an Issue: cssnr/vitepress-plugin-contributors/issues
- Chat with us on Discord: https://discord.gg/wXy6m2X8wY
- Provide General Feedback: https://cssnr.github.io/feedback/
- SwiperJS - Photo Gallery
- Contributors - GitHub Contributors
- Copy Button - Copy Text Button
All contributions are welcome including bug reports, feature requests, or pull requests.
For instructions on creating a PR for the Package or Documentation,
see the CONTRIBUTING.md.
Please consider making a donation to support the development of this project and additional open source projects.
For a full list of current projects visit: https://cssnr.github.io/