https://github.com/cssnr/vitepress-plugin-contributors
VitePress Plugin to easily display GitHub contributors and automatically updated on every install/deploy
https://github.com/cssnr/vitepress-plugin-contributors
vitepress-plugin
Last synced: 2 months ago
JSON representation
VitePress Plugin to easily display GitHub contributors and automatically updated on every install/deploy
- Host: GitHub
- URL: https://github.com/cssnr/vitepress-plugin-contributors
- Owner: cssnr
- License: gpl-3.0
- Created: 2025-09-12T22:46:54.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-09-13T02:17:29.000Z (9 months ago)
- Last Synced: 2025-09-13T02:23:56.659Z (9 months ago)
- Topics: vitepress-plugin
- Language: JavaScript
- Homepage:
- Size: 46.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors)
[](https://github.com/cssnr/vitepress-plugin-contributors/releases)
[](https://npm-stat.com/charts.html?package=%40cssnr%2Fvitepress-plugin-contributors)
[](https://bundlephobia.com/package/@cssnr/vitepress-plugin-contributors)
[](https://github.com/cssnr/vitepress-plugin-contributors/deployments/npm)
[](https://github.com/cssnr/vitepress-plugin-contributors/deployments/docs)
[](https://github.com/cssnr/vitepress-plugin-contributors/actions/workflows/release.yaml)
[](https://github.com/cssnr/vitepress-plugin-contributors/actions/workflows/lint.yaml)
[](https://github.com/cssnr/vitepress-plugin-contributors/pulse)
[](https://github.com/cssnr/vitepress-plugin-contributors?tab=readme-ov-file#readme)
[](https://github.com/cssnr/vitepress-plugin-contributors?tab=readme-ov-file#readme)
[](https://github.com/cssnr/vitepress-plugin-contributors/graphs/contributors)
[](https://github.com/cssnr/vitepress-plugin-contributors/issues)
[](https://github.com/cssnr/vitepress-plugin-contributors/discussions)
[](https://github.com/cssnr/vitepress-plugin-contributors/forks)
[](https://github.com/cssnr/vitepress-plugin-contributors/stargazers)
[](https://cssnr.github.io/)
[](https://discord.gg/wXy6m2X8wY)
[](https://ko-fi.com/cssnr)
# VitePress Plugin Contributors
- [Install](#Install)
- [Usage](#Usage)
- [Options](#Options)
- [Demos](#Demos)
- [Support](#Support)
- [Contributing](#Contributing)
A [VitePress](https://vitepress.dev/) Plugin to Easily generate, update and display repository Contributors.
Supports GitHub (including Enterprise) and Forgejo (Gitea, Codeberg, etc.).
This [package](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors) includes two components that can be use together or individually.
1. [get-contributors](src/get-contributors.js) - script to generate the `contributors.json` file.
2. [Contributors.vue](src/Contributors.vue) - component to display the contributors in VitePress.
Also includes a detailed [Installation](#install) guide with available [Support](#support).
[](https://vitepress-contributors.cssnr.com/)
## Install
[](https://vitepress-contributors.cssnr.com/guides/get-started#install)
1. Install directly into your VitePress from [npmjs](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors).
```shell
npm i @cssnr/vitepress-plugin-contributors
```
2. Add the [get-contributors](src/get-contributors.js) 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
[](https://vitepress-contributors.cssnr.com/docs/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 |
| `-G`/`--github` | `https://api.github.com` | GitHub API URL (for Enterprise) |
| `-F`/`--forgejo` | - | Forgejo API URL (for Gitea/Codeberg) |
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](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-primary-rate-limits) 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](#usage), add these lines for simplicity.
`VPBadge` - Only required if you are using the VitePress [Badge](https://vitepress.dev/reference/default-theme-badge#badge).
More Details on the contributors.json path
Note, you may need to modify the `../contributors.json` import location to match your setup.
If your VitePress configuration directory is located at `.vitepress` then the default output
path of `.vitepress/contributors.json` 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](#usage) for more details.
---
6. Finally, use the [Contributors.vue](src/Contributors.vue) component in your markdown or component.
```markdown
```
See the [Usage](#usage) for more details...
## Usage
[](https://vitepress-contributors.cssnr.com/guides/get-started#usage)
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
import contributors from '../.vitepress/contributors.json'
```
The `contributors.json` file is relative to the file you are importing it in.
See the [Options](#options) for more details...
## Options
[](https://vitepress-contributors.cssnr.com/docs/contributors)
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 |
| **max-users** | - | String | Max Number of users to display |
| **heading** | - | String | Optional Heading text |
| **size** | `64` | String | Size of Icons in pixels |
| **margin** | - | String | [CSS margin](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) string for container |
Example with all arguments.
```markdown
```
[](https://github.com/cssnr/vitepress-plugin-contributors?tab=readme-ov-file#readme)
## Demos
The plugin is running on these pages:
- https://django-files.github.io/ and [/team](https://django-files.github.io/team)
- https://docker-deploy.cssnr.com/
- https://portainer-deploy.cssnr.com/
If you have a live demo, [let us know](#support) and we will post it here...
## Support
Logs can be found inspecting the page (Ctrl+Shift+I), clicking on the Console, and;
Firefox: toggling Debug logs, Chrome: toggling Verbose from levels dropdown.
If you run into any issues or need help getting started, please do one of the following:
- Report an Issue:
- Q&A Discussion:
- Request a Feature:
- Chat with us on Discord:
[](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml)
[](https://github.com/cssnr/vitepress-plugin-contributors/issues)
[](https://github.com/cssnr/vitepress-plugin-contributors/discussions)
[](https://discord.gg/wXy6m2X8wY)
### More VitePress Plugins
- [SwiperJS](https://github.com/cssnr/vitepress-swiper) - Photo Gallery
- [Contributors](https://github.com/cssnr/vitepress-plugin-contributors) - GitHub Contributors
- [Copy Button](https://github.com/cssnr/vitepress-plugin-copybutton) - Copy Text Button
# Contributing
All contributions are welcome including [bug reports](https://github.com/cssnr/vitepress-plugin-contributors/issues), [feature requests](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml), or pull requests.
For instructions on creating a PR for the [Package](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors) or [Documentation](https://vitepress-contributors.cssnr.com/),
see the [CONTRIBUTING.md](#contributing-ov-file).
Please consider making a donation to support the development of this project and additional open source projects.
[](https://ko-fi.com/cssnr)
For a full list of current projects visit: [https://cssnr.github.io/](https://cssnr.github.io/)
