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/

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.

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 |

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.

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

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/

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/