remark plugin to inject Git contributors into a Markdown table


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
90Feb 16, 2021Jun 3, 2018Minified + gzip package size for remark-git-contributors in KB



Version Travis AppVeyor Coverage Dependencies JavaScript Style Guide Downloads Size Sponsors Backers Chat

remark plugin to inject Git contributors into a Markdown table. Collects contributors from Git history, deduplicates them, augments it with metadata found in options, a module, or package.json and calls remark-contributors to render the Markdown table.




npm install remark-git-contributors


With remark-cli, modifying a Markdown file in place (-o):

remark --use remark-git-contributors -o


Injecting a contributors section is opt-in: if a Contributors heading is not found in the Markdown (case- and level-insensitive), the plugin doesn’t do anything, unless appendIfMissing is set.

If the Git repository has many contributors, it is recommended to have them listed in a rather than To achieve this, add a Contributors heading to a but not to, prior to running remark. This way you can use the same pipeline (possibly with other plugins) on both files, only injecting contributors into one:

remark --use remark-git-contributors -o


To augment user metadata, configure the plugin in your package.json:

"remarkConfig": {
  "plugins": [
        "contributors": /* … */

Where contributors is either:

  • An array in the form of [{ email, name, … }, … ];
  • A module id or path to a file that exports contributors or { contributors }.

Note that remark-git-contributors excludes people that are not in Git history. This way the contributors metadata can be reused in multiple projects. Each contributor should at least have an email property to match against Git email addresses. To counter the fact that people change their email address, contributors are also matched by name if present.

As a shortcut you can replace the options object with a module id. For example, level-js uses metadata stored in level-community:

"remarkConfig": {
  "plugins": {
    "remark-git-contributors": "level-community"

Here’s an example of inline metadata:

"remarkConfig": {
  "plugins": {
    "remark-git-contributors": {
      "contributors": [{
        "name": "Sara",
        "email": "",
        "github": "sara"

Alternatively, put the metadata in the author or contributors fields in package.json. For example:

"author": {
  "name": "Sara",
  "email": "",
  "github": "sara"

If you’re experiencing people showing up multiple times from the Git history, for example because they switched email addresses while contributing to the project, or if their name or email are wrong, you can “merge” and fix contributors in Git by using a .mailmap file.

Supported properties

  • name: overrides the name stored in git commits
  • github: GitHub username
  • twitter: Twitter username
  • mastodon: Mastodon with format @user@domain


remark().use(gitContributors[, options])

Inject Git contributors into a Markdown table.


Limit the rendered contributors (number, default: 0). A limit of 0 (or lower) includes all contributors. If limit is given, only the top <limit> contributors, sorted by commit count, are rendered.


Contributor metadata (Array or string, default: []). Can be a list of contributor objects (see above). Can be a module id, that resolves either to a list of contributors or to an object with a contributors or default field that provides the list of contributors.


Working directory from which to resolve a contributors module, if any (string, default: file.cwd or process.cwd()).


Inject a Contributors section if there is none (boolean, default: false).


remark-git-contributors is typically used in a trusted environment. This section explains potential attack vectors and how to mitigate them if the environment is not (fully) trusted.

options.contributors (or contributors in package.json) and author from package.json are used and injected into the tree. git log also runs in the current working directory. This could open you up to a cross-site scripting (XSS) attack if you pass user provided content in or store user provided content in package.json or Git.

This may become a problem if the Markdown later transformed to rehype (hast) or opened in an unsafe Markdown viewer.

If contributors is a string, it is handled as a module identifier and loaded with require. This could also be very dangerous if an attacker was able to inject code in that package.


See in remarkjs/.github for ways to get started. See for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.


Name GitHub Social
Vincent Weevers @vweevers @vweevers@twitter
Titus Wormer @wooorm @wooorm@twitter


MIT © Vincent Weevers

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from