VitePress Plugin Contributors

• Install
• Usage
• Options
• Demos
• Support
• Contributing

A VitePress Plugin to Easily generate, update and display repository Contributors. Supports GitHub (including Enterprise) and Forgejo (Gitea, Codeberg, etc.).

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.

Install

1. Install directly into your VitePress from npmjs.

npm i @cssnr/vitepress-plugin-contributors

2. Add the get-contributors script to your package.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.

npx get-contributors user/repo

Limit to top 20 contributors, specify output file, and include bot users.

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 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.

.vitepress/contributors.json

4. Generate the contributors.json file.

npm run get-contributors

Alternatively, if you did not add the get-contributors script from step #2.

npx get-contributors user/repo

5. Import the components in your .vitepress/theme/index.js.

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. 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 for more details.

---

6. Finally, use the Contributors.vue component in your markdown or component.

<Contributors :contributors="$contributors" />

See the Usage for more details...

Usage

To use, simply add the <Contributors> tag to your markdown file (or component).

If you added contributors as a global component, you only need the <Contributors> tag.

<Contributors :contributors="$contributors" />

Otherwise, import the contributors.json and add a <Contributors> tag.

<script setup>
import contributors from '../.vitepress/contributors.json'
</script>

<Contributors :contributors="contributors" />

The contributors.json file is relative to the file you are importing it in.

See the Options for more details...

Options

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 string for container

Example with all arguments.

<Contributors
    :contributors="$contributors"
    heading="VitePress Contributors"
    max-users="98"
    size="48"
    margin="36px 0 96px"
/>

Demos

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...

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: https://github.com/cssnr/vitepress-plugin-contributors/issues
• Q&A Discussion: https://github.com/cssnr/vitepress-plugin-contributors/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

More VitePress Plugins

• SwiperJS - Photo Gallery
• Contributors - GitHub Contributors
• Copy Button - Copy Text Button

Contributing

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/