# @hperchec/readme-generator

> A useful README file generator using .ejs template

Latest version **3.1.0** (published 2024-12-20) · ISC license · 0 weekly downloads

## Install

```sh
npm install @hperchec/readme-generator
pnpm add @hperchec/readme-generator
yarn add @hperchec/readme-generator
bun add @hperchec/readme-generator
```

Provides the command `readme-generator`.

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2024-12-20 |
| First published | 2019-12-01 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 12 |
| Unpacked size | 52.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Hervé Perchec |
| Maintainers | herveperchec |
| Keywords | readme, generator, documentation, markdown, md, ejs, templater |

## Links

- npm: https://www.npmjs.com/package/@hperchec/readme-generator
- Repository: https://github.com/hperchec/readme-generator
- Homepage: https://github.com/hperchec/readme-generator#readme
- Issues: https://github.com/hperchec/readme-generator/issues
- npm.io page: https://npm.io/package/@hperchec/readme-generator

## Dependencies (12)

- [ejs](https://npm.io/package/ejs.md) ^3.1.9
- [execa](https://npm.io/package/execa.md) ^5.1.1
- [yargs](https://npm.io/package/yargs.md) ^17.7.2
- [prompts](https://npm.io/package/prompts.md) ^2.4.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^11.1.1
- [yargonaut](https://npm.io/package/yargonaut.md) ^1.1.4
- [ascii-tree](https://npm.io/package/ascii-tree.md) ^0.3.0
- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2
- [markdown-toc](https://npm.io/package/markdown-toc.md) ^1.2.0
- [github-slugger](https://npm.io/package/github-slugger.md) ^1.5.0
- [markdown-table](https://npm.io/package/markdown-table.md) ^1.1.3
- [markdown-utils](https://npm.io/package/markdown-utils.md) ^1.0.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 3.1.0 (latest) — 2024-12-20
- 2.0.0-beta.3 (beta) — 2023-10-11
- 3.0.0 — 2024-06-25
- 2.3.1 — 2023-10-16
- 2.3.0 — 2023-10-16
- 2.2.0 — 2023-10-12
- 2.1.0 — 2023-10-12
- 2.0.1 — 2023-10-12
- 2.0.0 — 2023-10-11
- 2.0.0-beta.2 — 2023-10-11
- 2.0.0-beta.1 — 2023-10-11
- 2.0.0-beta.0 — 2023-10-10
- 2.0.0-beta — 2023-10-10
- 1.0.4 — 2020-06-30
- 1.0.3 — 2020-06-30
- … 6 more at https://npm.io/package/@hperchec/readme-generator/versions

## README

# @hperchec/readme-generator

[![author](https://img.shields.io/static/v1?label=&message=Author:&color=black)
![herve-perchec](http://herve-perchec.com/badge.svg)](http://herve-perchec.com/)

[![package](https://img.shields.io/npm/v/@hperchec/readme-generator?logo=npm)](https://www.npmjs.com/package/@hperchec/readme-generator)
[![downloads](https://img.shields.io/npm/dw/@hperchec/readme-generator?logo=npm)](https://www.npmjs.com/package/@hperchec/readme-generator)
[![issues](https://img.shields.io/github/issues/open/https://github.com/hperchec/readme-generator?gitlab_url=https%3A%2F%2Fgitlab.com)](https://github.com/hperchec/readme-generator/issues)
![license](https://img.shields.io/github/license/https://github.com/hperchec/readme-generator?gitlab_url=https%3A%2F%2Fgitlab.com)

> Please consider following this project's author, [Hervé Perchec](https://github.com/hperchec), and consider starring the project to show your ❤ and support.

❔ **Why**

This project is an alternative of [verb](https://www.npmjs.com/package/verb).
It is partially inspired from and sounds like a "lightweight" version specially designed for README.md file.

👇 **Table of contents:**

- [🚀 Get started](#-get-started)
- [⚙ Configuration](#-configuration)
- [🧩 EJS template](#-ejs-template)
  - [Data](#data)
  - [Template](#template)
    - [Built-in EJS partials](#built-in-ejs-partials)
- [🌠 Generate README](#-generate-readme)
- [🦾 API](#-api)
- [⏫ Migrate from v1](#-migrate-from-v1)
- [🧱 Dependencies](#-dependencies)
- [🧪 Next features](#-next-features)
- [🤝 Contributing](#-contributing)
- [🎖 License](#-license)

## 🚀 Get started

> Engine compatibility
>
> - node 18.20.0
>
> See also [browserslist documentation](https://browsersl.ist/)

Install package via npm

``` bash
npm install -D @hperchec/readme-generator
```

Initialize

``` bash
readme-generator init
# Or use npx
npx readme-generator init
```

This will create a `./.docs/readme` folder at the root of your project

```
<your_project_root>
├─ ...
├─ .docs
│  └─ readme
│     ├─ config.js
│     ├─ data.js
│     └─ template.md
└─ ...
```

Add a script to your `package.json` file:

```bash
{
  "scripts": {
    # 'npm run readme' will generates your README.md file
    "readme": "readme-generator --config ./.docs/readme/config.js",
    # ...
  }
}
```

## ⚙ Configuration

You can pass custom configuration in the `./.docs/readme/config.js` file (all keys are optional).

**Example**:

```js
/**
 * .docs/readme/config.js
 */

module.exports = {
  /**
   * Output file name: 'README.md' by default
   */
  fileName: 'README.md'
}
```

> ❕ **NOTE**: Please check also the [documentation](./documentation/api.md) to learn more about configuration.

## 🧩 EJS template

This library uses [EJS](https://ejs.co/) as template engine.

### Data

Export your (ejs) data in the `./.docs/readme/data.js` file.

The exported data object will be merged into default passed to EJS. See also the EJS data relative [documentation](./documentation/api.md).

**Example**:

```js
/**
 * .docs/readme/data.js
 */

// Import package.json data
const pkg = require('../../package.json')
const repositoryUrl = pkg.repository.url
const dependencies = pkg.dependencies || {}
const devDependencies = pkg.devDependencies || {}

/**
 * Export data for readme file templating
 */
module.exports = {
  pkg,
  repositoryUrl,
  dependencies,
  devDependencies
}
```

### Template

Make your own template in `./.docs/readme/template.md` file.

**Example**:

```markdown
<%# 
  README.md template
-%>
# Awesome project!

👇 **Table of contents:**

<!-- toc -->

## Get started

Clone this [repository](<%= repositoryUrl %>) and install via `npm install`

## Dependencies

<details>

<summary>Global</summary>

<%-
  await include('common/table.md', {
    options: [
      ['name', 'version'],
      ...(Object.entries(dependencies))
    ]
  })
%>

</details>

<details>
```

The `<!-- toc -->` special comment will be replaced by auto-generated table of contents. See configuration documentation.

> ❕ **NOTE**: You can escape special toc comment by adding a backslash before the exclamation point "!" like: `<\!--`.

#### Built-in EJS partials

There are some partials used by default with EJS:

- `common/table.md`: render a table with `markdown-table` package

## 🌠 Generate README

```bash
npm run readme
```

Enjoy! 👍

> ❕ **NOTE**: The README file will be overwritten every time the command is runned.

## 🦾 API

Consult the [API documentation](./documentation/api.md)

## ⏫ Migrate from v1

> All configuration keys are now **optional**

The following have been renamed:

- `outputName` to `fileName`
- `outputPath` to `destFolder`

## 🧱 Dependencies

<details>

<summary>Global</summary>

| name           | version |
| -------------- | ------- |
| ascii-tree     | ^0.3.0  |
| ejs            | ^3.1.9  |
| execa          | ^5.1.1  |
| fs-extra       | ^11.1.1 |
| github-slugger | ^1.5.0  |
| lodash.merge   | ^4.6.2  |
| markdown-table | ^1.1.3  |
| markdown-toc   | ^1.2.0  |
| markdown-utils | ^1.0.0  |
| prompts        | ^2.4.2  |
| yargonaut      | ^1.1.4  |
| yargs          | ^17.7.2 |

</details>

<details>

<summary>Dev</summary>

| name                            | version  |
| ------------------------------- | -------- |
| @commitlint/cli                 | ^17.7.2  |
| @commitlint/config-conventional | ^17.7.0  |
| @hperchec/jsdoc-plugin-define   | ^1.0.1   |
| conventional-changelog-cli      | ^4.1.0   |
| cross-env                       | ^7.0.3   |
| eslint                          | ^8.51.0  |
| eslint-config-standard          | ^17.1.0  |
| eslint-plugin-disable           | ^2.0.3   |
| eslint-plugin-import            | ^2.28.1  |
| eslint-plugin-jsdoc             | ^46.8.2  |
| eslint-plugin-node              | ^11.1.0  |
| eslint-plugin-promise           | ^6.1.1   |
| eslint-plugin-standard          | ^4.1.0   |
| jsdoc-to-markdown               | ^8.0.0   |
| lint-staged                     | ^14.0.1  |
| npm-check-updates               | ^16.14.5 |
| simple-git-hooks                | ^2.9.0   |

</details>

<details>

<summary>Peer</summary>

| name | version |
| ---- | ------- |

</details>

## 🧪 Next features

- presets ? (GitHub/GitLab)

## 🤝 Contributing

> Please check the [contributing guidelines](./CONTRIBUTING.md)

## 🎖 License

ISC

----

Made with ❤ by [Hervé Perchec](https://github.com/hperchec)

----

*README.md - this file was auto generated with [@hperchec/readme-generator](https://www.npmjs.com/package/@hperchec/readme-generator). Don't edit it.*

---
_Source: https://npm.io/package/@hperchec/readme-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._