1.3.1 • Published 10 months ago

readme-md v1.3.1

Weekly downloads
3
License
MIT
Repository
github
Last release
10 months ago

readme-md

npm Version Node.js GitHub License CI Status

A README.md generator library.

Install

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

Usage

NOTE: This library exports both CJS and ESM modules.

JavaScript (Basic)

import readme from 'readme-md';

const pkg = {
    name: 'my-awesome-package',
    description: 'An awesome package.',
    type: 'module',
    license: 'MIT',
    scripts: {
        test: 'jest'
    }
};

readme({ pkg });
// > my-awesome-package
// > ==================
// > An awesome package.
// >
// > Install
// > -------
// > ```bash
// > npm install my-awesome-package
// > ```
// >
// > Usage
// > -----
// > ```js
// > import myAwesomePackage from 'my-awesome-package';
// > ```
// >
// > Testing
// > -------
// > ```bash
// > npm test
// > ```
// >
// > License
// > -------
// > The MIT License. See the license file for details.

JavaScript (Advanced)

import readme from 'readme-md';

const pkg = {
    name: 'my-awesome-package',
    description: 'An awesome package.',
    type: 'module',
    license: 'MIT',
    scripts: {
        test: 'jest'
    },
    engines: {
        yarn: '1.x'
    }
};

const additionalSections = [
    {
        position: 'before:Install',
        title: 'Greetings',
        body: 'Hello world!'
    }
];

const badges = [
    {
        alt: 'Build Status',
        image: 'https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat',
        link: 'https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml'
    }
];

const licenseLink = 'LICENSE';

readme({ pkg, additionalSections, badges, licenseLink });
// > my-awesome-package
// > ==================
// > [![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)
// >
// > An awesome package.
// >
// > Greetings
// > ---------
// > Hello world!
// >
// > Install
// > -------
// > ```bash
// > yarn add my-awesome-package # Or alternatively: `npm install my-awesome-package`
// > ```
// >
// > Usage
// > -----
// > ```js
// > import myAwesomePackage from 'my-awesome-package';
// > ```
// >
// > Testing
// > -------
// > ```bash
// > yarn test # Or alternatively: `npm test`
// > ```
// >
// > License
// > -------
// > The MIT License. See the [license file](LICENSE) for details.

TypeScript (Advanced)

import readme, { type ReadmeConfig } from 'readme-md';

const config: ReadmeConfig = {
    pkg: {
        name: 'my-awesome-package',
        description: 'An awesome package.',
        type: 'module',
        license: 'MIT',
        scripts: {
            test: 'jest'
        },
        engines: {
            yarn: '1.x'
        }
    },
    additionalSections: [
        {
            position: 'before:Install',
            title: 'Greetings',
            body: 'Hello world!'
        }
    ],
    badges: [
        {
            alt: 'Build Status',
            image: 'https://img.shields.io/github/actions/workflow/status/jbenner-radham/node-readme-md/ci.yaml?branch=main&logo=github&style=flat',
            link: 'https://github.com/jbenner-radham/node-readme-md/actions/workflows/ci.yaml'
        }
    ],
    licenseLink: 'LICENSE'
};

readme(config);
// > my-awesome-package
// > ==================
// > [![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)
// >
// > An awesome package.
// >
// > Greetings
// > ---------
// > Hello world!
// >
// > Install
// > -------
// > ```bash
// > yarn add my-awesome-package # Or alternatively: `npm install my-awesome-package`
// > ```
// >
// > Usage
// > -----
// > ```js
// > import myAwesomePackage from 'my-awesome-package';
// > ```
// >
// > Testing
// > -------
// > ```bash
// > yarn test # Or alternatively: `npm test`
// > ```
// >
// > License
// > -------
// > The MIT License. See the [license file](LICENSE) for details.

API

import type { PackageJson } from 'type-fest';

/**
 * Generates a readme document based upon the provided config.
 */
export default function readme(config?: ReadmeConfig): string;

export interface ReadmeConfig {
    /**
     * Additional sections to add to the readme.
     */
    additionalSections?: Section[];

    /**
     * Badges to add to the readme.
     */
    badges?: Badge[];

    /**
     * Add a hero image to the readme, below the description.
     */
    heroImage?: HeroImage;

    /**
     * While the license is derived from the `pkg.license` option this specifies
     * a link target to the license itself. If defined as `true` it will default
     * to setting the link target to "LICENSE". Please note that if
     * `pkg.license` is not defined this setting will have no effect.
     */
    licenseLink?: boolean | string;

    /**
     * The contents of a `package.json` to parse to generate the readme.
     */
    pkg?: PackageJson;

    /**
     * Whether the package should be shown as being installed as a dev
     * dependency in the "Install" section of the readme. Defaults to `false`.
     */
    preferDev?: boolean;

    /**
     * The package manager used in the "Install" and "Testing" sections defaults
     * to npm. However, this can be changed by specifying a package manager
     * (pnpm, Yarn) in `pkg.engines`. If desired set this to `true` to override
     * any package manager specified and utilize npm. Defaults to `false`.
     */
    preferNpm?: boolean;

    /**
     * Whether the example code in the "Usage" section should be terminated by
     * semicolons. Defaults to `true`.
     */
    preferSemicolons?: boolean;

    /**
     * The type of quotes used in the "Usage" section. Defaults to single
     * quotes.
     */
    quoteType?: 'double' | 'single';

    /**
     * Override any of the default generated sections.
     */
    sectionOverrides?: SectionOverrides;
}

export interface Section {
    /**
     * The position of the section in the readme. If not specified the section
     * will be appended onto the end of the readme. If a number is specified it
     * can be either positive or negative.
     */
    position?: number | PositionDirective;

    /**
     * The title of the section.
     */
    title: string;

    /**
     * The section body. If not specified it will default to the placeholder
     * text.
     */
    body?: string;
}

export interface HeroImage {
    /**
     * The image alt tag.
     */
    alt: string;

    /**
     * The image URL or path.
     */
    src: string;
}

/**
 * A `PositionDirective` is a string which begins with either "before:" or
 * "after:" and the section title to search for.
 *
 * @example
 * { position: 'after:Install' }
 * @example
 * { position: 'before:License' }
 */
export type PositionDirective = string;

export interface Badge {
    /**
     * The image alt tag.
     */
    alt: string;

    /**
     * The image URL.
     */
    image: string;

    /**
     * The link target of the image.
     */
    link: string;
}

export interface SectionOverrides {
    /**
     * Override for the "Install" section body text.
     */
    install?: string;

    /**
     * Override for the "Usage" section body text.
     */
    usage?: string;

    /**
     * Override for the "Testing" section body text.
     */
    testing?: string;

    /**
     * Override for the "License" section body text.
     */
    license?: string;
}

Testing

yarn test # Or alternatively: `npm test`

See Also

License

The MIT License. See the license file for details.

1.3.1

10 months ago

1.3.0

10 months ago

1.2.0

11 months ago

1.1.0

11 months ago

1.0.0

11 months ago

1.2.1

11 months ago

0.14.0

1 year ago

0.15.0

11 months ago

0.10.0

3 years ago

0.11.0

3 years ago

0.9.0

3 years ago

0.12.0

3 years ago

0.13.0

3 years ago

0.13.1

3 years ago

0.8.0

8 years ago

0.7.0

8 years ago

0.6.0

8 years ago

0.5.0

8 years ago

0.4.0

8 years ago

0.3.0

8 years ago

0.2.0

8 years ago

0.1.0

8 years ago

0.1.0-beta.1

8 years ago

0.1.0-alpha.2

8 years ago

0.1.0-alpha.1

8 years ago