readme-md

A README.md generator library.

Install

1yarn add readme-md # Or alternatively: `npm install readme-md`

Usage

NOTE: This library exports both CJS and ESM modules.

JavaScript (Basic)

1import readme from 'readme-md';
2
3const pkg = {
4    name: 'my-awesome-package',
5    description: 'An awesome package.',
6    type: 'module',
7    license: 'MIT',
8    scripts: {
9        test: 'jest'
10    }
11};
12
13readme({ pkg });
14// > my-awesome-package
15// > ==================
16// > An awesome package.
17// >
18// > Install
19// > -------
20// > ```sh
21// > npm install my-awesome-package
22// > ```
23// >
24// > Usage
25// > -----
26// > ```js
27// > import myAwesomePackage from 'my-awesome-package';
28// > ```
29// >
30// > Testing
31// > -------
32// > ```sh
33// > npm test
34// > ```
35// >
36// > License
37// > -------
38// > The MIT License. See the license file for details.

JavaScript (Advanced)

1import readme from 'readme-md';
2
3const pkg = {
4    name: 'my-awesome-package',
5    description: 'An awesome package.',
6    type: 'module',
7    license: 'MIT',
8    scripts: {
9        test: 'jest'
10    },
11    engines: {
12        yarn: '1.x'
13    }
14};
15
16const additionalSections = [
17    {
18        position: 'before:Install',
19        title: 'Greetings',
20        body: 'Hello world!'
21    }
22];
23
24const badges = [
25    {
26        alt: 'Build Status',
27        image: 'https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat',
28        link: 'https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml'
29    }
30];
31
32const licenseLink = 'LICENSE';
33
34readme({ pkg, additionalSections, badges, licenseLink });
35// > my-awesome-package
36// > ==================
37// > [![Build Status](https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat)](https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml)
38// >
39// > An awesome package.
40// >
41// > Greetings
42// > ---------
43// > Hello world!
44// >
45// > Install
46// > -------
47// > ```sh
48// > yarn add my-awesome-package # Or alternatively: `npm install my-awesome-package`
49// > ```
50// >
51// > Usage
52// > -----
53// > ```js
54// > import myAwesomePackage from 'my-awesome-package';
55// > ```
56// >
57// > Testing
58// > -------
59// > ```sh
60// > yarn test # Or alternatively: `npm test`
61// > ```
62// >
63// > License
64// > -------
65// > The MIT License. See the [license file](LICENSE) for details.

TypeScript (Advanced)

1import readme, { type ReadmeConfig } from 'readme-md';
2
3const config: ReadmeConfig = {
4    pkg: {
5        name: 'my-awesome-package',
6        description: 'An awesome package.',
7        type: 'module',
8        license: 'MIT',
9        scripts: {
10            test: 'jest'
11        },
12        engines: {
13            yarn: '1.x'
14        }
15    },
16    additionalSections: [
17        {
18            position: 'before:Install',
19            title: 'Greetings',
20            body: 'Hello world!'
21        }
22    ],
23    badges: [
24        {
25            alt: 'Build Status',
26            image: 'https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat',
27            link: 'https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml'
28        }
29    ],
30    licenseLink: 'LICENSE'
31};
32
33readme(config);
34// > my-awesome-package
35// > ==================
36// > [![Build Status](https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat)](https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml)
37// >
38// > An awesome package.
39// >
40// > Greetings
41// > ---------
42// > Hello world!
43// >
44// > Install
45// > -------
46// > ```sh
47// > yarn add my-awesome-package # Or alternatively: `npm install my-awesome-package`
48// > ```
49// >
50// > Usage
51// > -----
52// > ```js
53// > import myAwesomePackage from 'my-awesome-package';
54// > ```
55// >
56// > Testing
57// > -------
58// > ```sh
59// > yarn test # Or alternatively: `npm test`
60// > ```
61// >
62// > License
63// > -------
64// > The MIT License. See the [license file](LICENSE) for details.

API

1import type { PackageJson } from 'type-fest';
2
3/**
4 * Generates a readme document based upon the provided config.
5 */
6export default function readme(config?: ReadmeConfig): string;
7
8export interface ReadmeConfig {
9    /**
10     * Additional sections to add to the readme.
11     */
12    additionalSections?: Section[];
13
14    /**
15     * Badges to add to the readme.
16     */
17    badges?: Badge[];
18
19    /**
20     * Add a hero image to the readme, below the description.
21     */
22    heroImage?: HeroImage;
23
24    /**
25     * While the license is derived from the `pkg.license` option this specifies
26     * a link target to the license itself. If defined as `true` it will default
27     * to setting the link target to "LICENSE". Please note that if
28     * `pkg.license` is not defined this setting will have no effect.
29     */
30    licenseLink?: boolean | string;
31
32    /**
33     * The contents of a `package.json` to parse to generate the readme.
34     */
35    pkg?: PackageJson;
36
37    /**
38     * Whether the package should be shown as being installed as a dev
39     * dependency in the "Install" section of the readme. Defaults to `false`.
40     */
41    preferDev?: boolean;
42
43    /**
44     * The package manager used in the "Install" and "Testing" sections defaults
45     * to npm. However, this can be changed by specifying a package manager
46     * (pnpm, Yarn) in `pkg.engines`. If desired set this to `true` to override
47     * any package manager specified and utilize npm. Defaults to `false`.
48     */
49    preferNpm?: boolean;
50
51    /**
52     * Whether the example code in the "Usage" section should be terminated by
53     * semicolons. Defaults to `true`.
54     */
55    preferSemicolons?: boolean;
56
57    /**
58     * The type of quotes used in the "Usage" section. Defaults to single
59     * quotes.
60     */
61    quoteType?: 'double' | 'single';
62
63    /**
64     * Override any of the default generated sections.
65     */
66    sectionOverrides?: SectionOverrides;
67}
68
69export interface Section {
70    /**
71     * The position of the section in the readme. If not specified the section
72     * will be appended onto the end of the readme. If a number is specified it
73     * can be either positive or negative.
74     */
75    position?: number | PositionDirective;
76
77    /**
78     * The title of the section.
79     */
80    title: string;
81
82    /**
83     * The section body. If not specified it will default to the placeholder
84     * text.
85     */
86    body?: string;
87}
88
89export interface HeroImage {
90    /**
91     * The image alt tag.
92     */
93    alt: string;
94
95    /**
96     * The image URL or path.
97     */
98    src: string;
99}
100
101/**
102 * A `PositionDirective` is a string which begins with either "before:" or
103 * "after:" and the section title to search for.
104 *
105 * @example
106 * { position: 'after:Install' }
107 * @example
108 * { position: 'before:License' }
109 */
110export type PositionDirective = string;
111
112export interface Badge {
113    /**
114     * The image alt tag.
115     */
116    alt: string;
117
118    /**
119     * The image URL.
120     */
121    image: string;
122
123    /**
124     * The link target of the image.
125     */
126    link: string;
127}
128
129export interface SectionOverrides {
130    /**
131     * Override for the "Install" section body text.
132     */
133    install?: string;
134
135    /**
136     * Override for the "Usage" section body text.
137     */
138    usage?: string;
139
140    /**
141     * Override for the "Testing" section body text.
142     */
143    testing?: string;
144
145    /**
146     * Override for the "License" section body text.
147     */
148    license?: string;
149}

Testing

1yarn test # Or alternatively: `npm test`

See Also

• readme-md-cli @ npm

License

The MIT License. See the license file for details.