remark-contributors/lib/index.d.ts

remark plugin to inject a given list of contributors into a table

/**
 * Generate a list of contributors.
 *
 * In short, this plugin:
 *
 * * looks for the first heading matching `/^contributors$/i` or
 *   `options.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
 *
 * ##### Notes
 *
 * * define fields other than `name`, `url`, `github`, or `twitter` in
 *   `formatters` to label them properly
 * * by default, fields named `url` will be labelled `Website` (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)
 *
 * @param {Readonly<Options> | null | undefined} [options]
 *   Configuration (optional).
 * @returns
 *   Transform.
 */
export default function remarkContributors(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => Promise<undefined>;
export type AlignType = import('mdast').AlignType;
export type BlockContent = import('mdast').BlockContent;
export type Root = import('mdast').Root;
export type RowContent = import('mdast').RowContent;
export type Table = import('mdast').Table;
export type TableContent = import('mdast').TableContent;
export type VFile = import('vfile').VFile;
export type Format = import('./formatters.js').Format;
export type FormatterObject = import('./formatters.js').FormatterObject;
export type FormatterObjects = import('./formatters.js').FormatterObjects;
export type Contributor = import('#get-contributors-from-package').Contributor;
export type ContributorObject = import('#get-contributors-from-package').ContributorObject;
/**
 * How to format a field, in short.
 *
 * The values can be:
 *
 * * `null` or `undefined` — 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
 */
export type Formatter = FormatterObject | boolean | string | null | undefined;
/**
 * Formatters for fields.
 */
export type Formatters = Record<string, Formatter>;
/**
 * Configuration.
 */
export type Options = {
    /**
     * Alignment to use for all cells in the table (optional).
     */
    align?: AlignType | undefined;
    /**
     * Inject the section if there is none (default: `false`);
     * the default does nothing when the section doesn’t exist so that you have
     * to choose where and if the section is added.
     */
    appendIfMissing?: boolean | null | undefined;
    /**
     * List of contributors to inject (default: contributors in `package.json`
     * in Node);
     * supports string form (`name <email> (url)`);
     * throws if no contributors are found or given.
     */
    contributors?: ReadonlyArray<Contributor> | null | undefined;
    /**
     * Map of fields found in `contributors` to formatters (optional);
     * these given formatters extend the default formatters.
     * the keys in `formatters` should correspond directly (case-sensitive) to
     * keys in `contributors`.
     */
    formatters?: Readonly<Formatters> | null | undefined;
    /**
     * Heading to look for (default: `'contributors'`).
     */
    heading?: RegExp | string | null | undefined;
};