# docs/contributors.md

# Contributors

Only the `:contributors` parameter is required, everything else is optional.

| Parameter              |   Default    |  Type  | Description of the Parameter                                                |
| :--------------------- | :----------: | :----: | :----------------------------------------------------------------------------------------- |
| `:contributors` <CB /> | **Required** | Array  | `contributors.json` file import data                                                       |
| `max-users` <CB />     |      -       | String | Max Number of users to display                                                             |
| `heading` <CB />       |      -       | String | Optional Heading text                                                                      |
| `size` <CB />          |     `64`     | String | Size of Icons in pixels                                                                    |
| `margin` <CB />        |      -       | String | [CSS margin](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) string for container |

## Usage

With all arguments.

```markdown
<Contributors
    :contributors="$contributors"
    heading="Contributors"
    max-users="22"
    size="48"
    margin="36px 0 24px"
/>
```

<Contributors :contributors="$contributors" heading="Contributors" max-users="22" size="48" margin="36px 0 24px" />

## 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 and we will post it here...

&nbsp;

::: tip Request a Feature
If you need more options, please [open a feature request](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml)
:::

<style>
.contributors-page table td:nth-child(1) {
  white-space: nowrap;
}
</style>

---

# docs/get-contributors.md

# Get Contributors

View the source: [get-contributors.ts](https://github.com/cssnr/vitepress-plugin-contributors/blob/master/src/get-contributors.ts)

Only the `user/repo` is required. All other arguments are optional.

| Argument&nbsp;Flag | Default&nbsp;Value             | Description&nbsp;of&nbsp;the&nbsp;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)       |

Show help: `npx get-contributors -h` <CB prev />

## Usage

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

::: details GitHub API Rate Limit

Note: Only applies to unauthenticated requests.

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

:::

### GitHub Enterprise

You can set the GitHub API url to use with `-G`.

```shell
npx get-contributors user/repo -G api.example.com
```

### Forgejo/Gitea/Codeberg

To use with the Forgejo API, set the url with `-F`.

```shell
npx get-contributors user/repo -F codeberg.org
```

For information on building, see the [Get Contributors Source](../guides/source#get-contributors-script) guide.

&nbsp;

::: tip Request a Feature
If you need more options, please [open a feature request](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml)
:::

---

# guides/get-started.md

# Getting Started

A [VitePress](https://vitepress.dev/) Plugin to Easily generate, update and display repository Contributors.

This [package](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors) includes two components that can be use together or individually.

1. [get-contributors](../docs/get-contributors.md) - script to generate the `contributors.json` file.
2. [Contributors.vue](../docs/contributors.md) - component to display the contributors in VitePress.

Start by [installing](#install) the package, [configuring](#configure) the script and [setting](#setup) up the plugin.

<Contributors :contributors="$contributors" heading="Top 6 VP Contributors" max-users="6" margin="36px 0 0" />

```markdown
<Contributors :contributors="$contributors" heading="Top 6 VP Contributors" max-users="6" margin="36px 0 0" />
```

## Install

<span class="search-keywords">Install or Download from NPM npmjs.com</span>

Install directly to your VitePress from [npmjs](https://www.npmjs.com/package/@cssnr/vitepress-plugin-contributors) with the following command.

::: code-group

```shell [npm]
npm i @cssnr/vitepress-plugin-contributors
```

```shell [pnpm]
pnpm i @cssnr/vitepress-plugin-contributors
```

```shell [yarn]
yarn add @cssnr/vitepress-plugin-contributors
```

```shell [bun]
bun i @cssnr/vitepress-plugin-contributors
```

:::

_Note: you can also [copy the source](source.md) file to your project._ <Badge type="warning">WIP</Badge>

## Configure

You need to configure the [get-contributors](../docs/get-contributors.md) script to run.

1. Add the [get-contributors](../docs/get-contributors.md) script to your `package.json`.

```json
{
  "scripts": {
    "get-contributors": "npx get-contributors user/repo", // [!code ++]
    "postinstall": "npm run get-contributors" // [!code ++]
  }
}
```

_If you don't add the `postinstall` script you need to add `get-contributors` to your build._

2. Add the `contributors.json` file location to your `.gitignore`.

```txt
.vitepress/contributors.json
```

3. Generate the `contributors.json` file.

::: code-group

```shell [Script ~vscode-icons:file-type-shell~]
npm run get-contributors
```

```shell [Without Script ~vscode-icons:file-type-shell~]
npx get-contributors user/repo
```

:::

<div class="tip custom-block" style="padding-top: 8px">

See the [Get Contributors Documentation](../docs/get-contributors.md) for usage details.

</div>

## Setup

Add these 3-5 lines to your `index.[js,ts]`.

_If you don't have a [.vitepress/theme/index.ts](https://vitepress.dev/guide/custom-theme#theme-resolving) file, create one._

```javascript [.vitepress/theme/index.ts]
import DefaultTheme, { VPBadge } from 'vitepress/theme' // [!code highlight]

import Contributors from '@cssnr/vitepress-plugin-contributors' // [!code ++]
import '@cssnr/vitepress-plugin-contributors/style.css' // [!code ++]

import contributors from '../contributors.json' // [!code warning]

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', VPBadge) // [!code highlight]

    app.component('Contributors', Contributors) // [!code ++]

    app.config.globalProperties.$contributors = contributors // [!code warning]
  },
}
```

If you are unsure about this [usage](#usage), add these lines for simplicity. <Badge type="warning">Global</Badge>

Only required if you are using the VitePress [Badge](https://vitepress.dev/reference/default-theme-badge#badge). <Badge type="info">VPBadge</Badge>

## Usage

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

::: code-group

```vue [Global ~vscode-icons:file-type-text~]
<Contributors :contributors="$contributors" />
```

```vue [Without Global ~vscode-icons:file-type-text~]
<script setup>
import contributors from '../.vitepress/contributors.json'
</script>

<Contributors :contributors="contributors" />
```

:::

<div class="tip custom-block" style="padding-top: 8px">

See the [Contributors Documentation](../docs/contributors.md) for **usage** details and more **examples**.

</div>

---

# guides/source.md

# Use from Source

::: warning Work in Progress
This guide is not yet complete but should get you started.
:::

You can easily add the source file to your project for full control over the [template](#contributors-component).

[[toc]]

## Contributors Component

Download or copy the [Contributors.vue](https://github.com/cssnr/vitepress-plugin-contributors/blob/master/src/Contributors.vue)
file to your project.

- Source File: [Contributors.vue](https://github.com/cssnr/vitepress-plugin-contributors/blob/master/src/Contributors.vue)
- Target Location: `.vitepress/theme/components/Contributors.vue`

Add these 2 lines to your `index.[js,ts]`.

```javascript [.vitepress/theme/index.ts]
import DefaultTheme from 'vitepress/theme'

import Contributors from './components/Contributors.vue' // [!code ++]

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Contributors', Contributors) // [!code ++]
  },
}
```

See the [Contributors Documentation](../docs/contributors.md) for `<Contributors>` tag usage and examples.

## Get Contributors Script

This can be [installed with npm](get-started.md#install), or you can manually copy it to your project.

- Source: [src/get-contributors](https://github.com/cssnr/vitepress-plugin-contributors/blob/master/src/get-contributors.ts)
- Latest Release: [get-contributors.mjs](https://github.com/cssnr/vitepress-plugin-contributors/releases/latest/download/get-contributors.mjs)

The **Latest Release** is a built, dependency free, version that can be run directly with [node](https://nodejs.org/).

To use the **Source** directly you need to install the dependency, [commander.js](https://github.com/tj/commander.js).

::: code-group

```shell [npm]
npm i commander
```

```shell [pnpm]
pnpm i commander
```

```shell [yarn]
yarn add commander
```

```shell [bun]
bun i commander
```

:::

See the [Get Contributors Documentation](../docs/get-contributors.md) for details on the `get-contributors` script.

### Building

To build `get-contributors.ts` without dependencies you can use [@vercel/ncc](https://www.npmjs.com/package/@vercel/ncc).

::: code-group

```shell [npm]
npm i -g @vercel/ncc
```

```shell [pnpm]
pnpm i -g @vercel/ncc
```

```shell [yarn]
yarn add -g @vercel/ncc
```

```shell [bun]
bun i -g @vercel/ncc
```

:::

Then you can build it like this.

::: code-group

```shell [Normal ~vscode-icons:file-type-shell~]
npx ncc build src/get-contributors.ts -o dist/get-contributors
```

```shell [Minified ~vscode-icons:file-type-shell~]
npx ncc build -m src/get-contributors.ts -o dist/get-contributors
```

:::

The resulting `dist/get-contributors/index.ts` can then be run without any dependencies.

---

# support.md

# Support

[![Features](https://img.shields.io/badge/features-brightgreen?style=for-the-badge&logo=rocket&logoColor=white)](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml)
[![Issues](https://img.shields.io/badge/issues-red?style=for-the-badge&logo=southwestairlines&logoColor=white)](https://github.com/cssnr/vitepress-plugin-contributors/issues)
[![Discussions](https://img.shields.io/badge/discussions-blue?style=for-the-badge&logo=theconversation)](https://github.com/cssnr/vitepress-plugin-contributors/discussions)
[![Discord](https://img.shields.io/badge/discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/wXy6m2X8wY)

If you run into any issues or want to see any new features, please let us know!

Contributing is as easy as telling us [what features or changes](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml) you want to see next…

[[toc]]

### GitHub Discussions

If you have a question or need help with anything,
start a discussion in [General](https://github.com/cssnr/vitepress-plugin-contributors/discussions/categories/general)
or [Q&A](https://github.com/cssnr/vitepress-plugin-contributors/discussions/categories/q-a).

If you want to see a new feature, start a discussion in
the [Feature Requests](https://github.com/cssnr/vitepress-plugin-contributors/issues/new?template=1-feature.yaml) section.

[![Start A Discussion](https://img.shields.io/badge/Start_A_Discussion-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/vitepress-plugin-contributors/discussions)

### GitHub Issues

If you run into any problems or find a bug, please [open an issue](https://github.com/cssnr/vitepress-plugin-contributors/issues).

**These reports are treated with the highest priority.**

[![Report an Issue](https://img.shields.io/badge/Report_an_Issue-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/vitepress-plugin-contributors/issues)

### Discord Chat

You can chat with us about anything [on discord](https://discord.gg/wXy6m2X8wY).

From here you can contact me directly, `Shane@111150265075298304`.

[![Chat on Discord](https://img.shields.io/badge/Chat_on_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/wXy6m2X8wY)