remark-git-contributors
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.
Note!
This plugin is ready for the new parser in remark (micromark
, see remarkjs/remark#536
). No change is needed: it works exactly the same now as it did before! (note that remark-gfm
must be used as well to support tables)
Contents
Install
npm:
npm install remark-git-contributors
Use
With remark-cli
, modifying a Markdown file in place (-o
):
remark --use remark-git-contributors readme.md -o
Inject
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 contributors.md
rather than readme.md
. To achieve this, add a Contributors
heading to a contributors.md
but not to readme.md
, 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 readme.md contributors.md -o
Metadata
To augment user metadata, configure the plugin in your package.json
:
"remarkConfig": {
"plugins": [
[
"remark-git-contributors",
{
"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": "sara@example.com",
"github": "sara"
}]
}
}
}
Alternatively, put the metadata in the author
or contributors
fields in package.json
. For example:
"author": {
"name": "Sara",
"email": "sara@example.com",
"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 commitsgithub
: GitHub usernametwitter
: Twitter usernamemastodon
: Mastodon with format@user@domain
API
remark().use(gitContributors[, options])
Inject Git contributors into a Markdown table.
options
options.limit
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.
options.contributors
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.
options.cwd
Working directory from which to resolve a contributors
module, if any (string
, default: file.cwd
or process.cwd()
).
options.appendIfMissing
Inject a Contributors section if there is none (boolean
, default: false
).
Security
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.
Contribute
See contributing.md
in remarkjs/.github
for ways to get started. See support.md
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.
Contributors
Name | GitHub | Social |
---|---|---|
Vincent Weevers | @vweevers | @vweevers@twitter |
Titus Wormer | @wooorm | @wooorm@twitter |
License
MIT © Vincent Weevers