remark-contributors
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatremark plugin to generate a list of contributors.
Contents
* [`unified().use(remarkContributors[, options])`](#unifieduseremarkcontributors-options)
* [`Contributor`](#contributor)
* [`ContributorObject`](#contributorobject)
* [`Format`](#format)
* [`Formatter`](#formatter)
* [`FormatterObject`](#formatterobject)
* [`Formatters`](#formatters)
* [`Options`](#options)
* [Example: passing contributors](#example-passing-contributors)
* [Example: formatters](#example-formatters)
What is this?
This package is a unified (remark) plugin that takes a list of contributors and adds them in a table to a## Contributors
heading.When should I use this?
This project is useful when you’re writing documentation for a project, typically a Node.js package, that has one or more readmes and maybe some other markdown files as well. You want to show who helped build the project by adding their names, websites, and perhaps some more info. This package is useful because it’s automated: you can customize who is added and how that’s formatted. But it won’t be as expressive as writing such sections manually.This plugin is used in
remark-git-contributors
remark-git-contributors.
The difference is that that plugin takes the Git history into account, which
isn’t always needed or correct.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install remark-contributors
In Deno with
esm.sh
esmsh:import remarkContributors from 'https://esm.sh/remark-contributors@7'
In browsers with
esm.sh
esmsh:<script type="module">
import remarkContributors from 'https://esm.sh/remark-contributors@7?bundle'
</script>
Use
Say we have the following fileexample.md
in this project:# Example
Some text.
## Contributors
## License
MIT
…and a module
example.js
:import {remark} from 'remark'
import remarkContributors from 'remark-contributors'
import remarkGfm from 'remark-gfm'
import {read} from 'to-vfile'
const file = await remark()
.use(remarkGfm) // This is needed to add support for tables (a GFM feature).
.use(remarkContributors)
.process(await read('example.md'))
console.log(String(file))
…then running
node example.js
yields:# Example
Some text.
## Contributors
| Name | Website |
| ------------------- | --------------------------- |
| **Hugh Kennedy** | <https://hughsk.io> |
| **Titus Wormer** | <https://wooorm.com> |
| **Vincent Weevers** | <https://vincentweevers.nl> |
| **Nick Baugh** | <https://niftylettuce.com> |
## License
MIT
👉 Note: These contributors are inferred from the
package.json
file-package-json in this project.
Running this example in a different package will yield different results.
API
This package exports no identifiers. The default export isremarkContributors
api-remark-contributors.unified().use(remarkContributors[, options])
Generate a list of contributors.In short, this plugin:
- looks for the first heading matching
/^contributors$/i
oroptions.heading
- if no heading is found and
appendIfMissing
is set, injects such a heading - if there is a heading, replaces everything in that section with a new table
Parameters
options
(Options
api-options, optional)
— configuration
Returns
Transform (Transformer
unified-transformer).Notes
- define fields other than
name
,url
,github
, ortwitter
in
`formatters` to label them properly
- by default, fields named
url
will be labelledWebsite
(so that
`package.json` contributors field is displayed nicely)
- by default, fields named
email
are ignored - name fields are displayed as strong
- GitHub and Twitter URLs are automatically stripped and displayed with
`@mention`s wrapped in an `https://` link
- if a field is undefined for a given contributor, then the value will be an
empty table cell
- columns are sorted in the order they are defined (first defined means first
displayed)
Contributor
Contributor in string form (name <email> (url)
) or as object (TypeScript
type).Type
type Contributor = ContributorObject | string
ContributorObject
Contributor with fields (TypeScript type).Type
type ContributorObject = Record<string, unknown>
Format
Format a field (TypeScript type).Parameters
value
(unknown
)
— value to format
key
(string
)
— name of a field in a contributor
contributor
(Contributor
api-contributor)
— whole contributor
Returns
Content (Array<PhrasingContent> | PhrasingContent | string
, optional)Formatter
How to format a field, in short (TypeScript type).The values can be:
null
orundefined
— does nothing;false
— shortcut for{exclude: true, label: key}
, can be used to
exclude default formatters;
true
— shortcut for{label: key}
, can be used to include default
formatters (like `email`)
string
— shortcut for{label: value}
Formatter
— …or a proper formatter object
Type
type Formatter = FormatterObject | boolean | string | null | undefined
FormatterObject
How to format a field (TypeScript type).Fields
exclude
(boolean
, default:false
)
— whether to ignore these fields
format
(Format
api-format, optional)
— How to format the cell
label
(string
, optional)
— text in the header row that labels the column for this field
Formatters
Formatters for fields (TypeScript type).Type
type Formatters = Record<string, Formatter>
Options
Configuration (TypeScript type).Fields
align
(AlignType
frommdast
mdast-align-type, optional)
— alignment to use for all cells in the table
appendIfMissing
(boolean
, default:false
)
— inject the section if there is none;
the default does nothing when the section doesn’t exist so that you have to
choose where and if the section is added
contributors
(Array<Contributor>
api-contributor, default:
contributors in `package.json` in Node)
— list of contributors to inject;
supports string form (`name <email> (url)`);
throws if no contributors are found or given
formatters
(string
, optional)
— map of fields found in `contributors` to formatters;
these given formatters extend the [default formatters][file-formatters];
the keys in `formatters` should correspond directly (case-sensitive) to
keys in `contributors`
heading
(RegExp | string
, default:'contributors'
)
— heading to look for
Examples
Example: passing contributors
The following example shows how contributors can be passed:import {remark} from 'remark'
import remarkContributors from 'remark-contributors'
import remarkGfm from 'remark-gfm'
const file = await remark()
.use(remarkGfm)
.use(remarkContributors, {
contributors: [
// String form:
'Jane Doe <jane@doe.com> (https://example.com/jane)',
// Object form, with just a name:
{name: 'John Doe'},
// Some more info:
{name: 'Mona Lisa', url: 'https://github.com/monatheoctocat'}
]
})
.process('## Contributors')
console.log(String(file))
Yields:
## Contributors
| Name | Website |
| ------------- | ----------------------------------- |
| **Jane Doe** | <https://example.com/jane> |
| **John Doe** | |
| **Mona Lisa** | <https://github.com/monatheoctocat> |
Example: formatters
By default, unknown fields in contributors will be added to the table:import {remark} from 'remark'
import remarkContributors from 'remark-contributors'
import remarkGfm from 'remark-gfm'
const file = await remark()
.use(remarkGfm)
.use(remarkContributors, {
contributors: [
{name: 'Jane Doe', age: 31, topping: 'Mozzarella'},
{name: 'John Doe', age: 29, topping: 'Olive'},
{name: 'Mona Lisa', age: 3, topping: 'Pineapple'}
]
})
.process('## Contributors')
console.log(String(file))
Yields:
## Contributors
| Name | age | topping |
| ------------- | --- | ---------- |
| **Jane Doe** | 31 | Mozzarella |
| **John Doe** | 29 | Olive |
| **Mona Lisa** | 3 | Pineapple |
It’s possible to customize how these new fields are formatted:
@@ -12,7 +12,16 @@ const file = await remark()
{name: 'Jane Doe', age: 31, topping: 'Mozzarella'},
{name: 'John Doe', age: 29, topping: 'Olive'},
{name: 'Mona Lisa', age: 3, topping: 'Pineapple'}
- ]
+ ],
+ formatters: {
+ age: {
+ label: 'Age',
+ format(d) {
+ return {type: 'emphasis', children: [{type: 'text', value: String(d)}]}
+ }
+ },
+ topping: 'Topping'
+ }
})
.process('## Contributors')
Yields:
| Name | Age | Topping |
| ------------- | ---- | ---------- |
| **Jane Doe** | *31* | Mozzarella |
| **John Doe** | *29* | Olive |
| **Mona Lisa** | *3* | Pineapple |
👉 Note: observe that the labels ofAge
andTopping
are now cased, and that the age values are now wrapped in emphasis.
Types
This package is fully typed with TypeScript. It exports the additional typesContributor
api-contributor,
ContributorObject
api-contributor-object,
Format
api-format,
Formatter
api-formatter,
FormatterObject
api-formatter-object,
Formatters
api-formatters, and
Options
api-options.Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line,
remark-contributors@^7
,
compatible with Node.js 16.This plugin works with
unified
version 6+ and remark
version 7+.Security
options.contributors
(or contributors
in package.json
) is used and
injected into the tree when given or found.
Data in those lists is formatted by options.formatters
.
If a user has access to either, this could open you up to a
cross-site scripting (XSS)wiki-xss attack.This may become a problem if the markdown is later transformed to rehype (hast) or opened in an unsafe markdown viewer.
Related
– very similar to this plugin but uses info from Git
– make a section collapsible
— make sure there is a single top level heading in a document by adjusting
heading ranks accordingly
— increase or decrease markdown heading ranks
— generate a table of contents (TOC)
— generate a license section
Contribute
Seecontributing.md
contributing in remarkjs/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.