@hperchec/readme-generator

Please consider following this project's author, Hervé Perchec, and consider starring the project to show your ❤ and support.

❔ Why

This project is an alternative of verb. It is partially inspired from and sounds like a "lightweight" version specially designed for README.md file.

👇 Table of contents:

• 🚀 Get started
• ⚙ Configuration
• 🧩 EJS template
  • Data
  • Template
    • Built-in EJS partials
• 🌠 Generate README
• 🦾 API
• ⏫ Migrate from v1
• 🧱 Dependencies
• 🧪 Next features
• 🤝 Contributing
• 🎖 License

🚀 Get started

Engine compatibility

• node 18.20.0

See also browserslist documentation

Install package via npm

1npm install -D @hperchec/readme-generator

Initialize

1readme-generator init
2# Or use npx
3npx 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:

1{
2  "scripts": {
3    # 'npm run readme' will generates your README.md file
4    "readme": "readme-generator --config ./.docs/readme/config.js",
5    # ...
6  }
7}

⚙ Configuration

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

Example:

1/**
2 * .docs/readme/config.js
3 */
4
5module.exports = {
6  /**
7   * Output file name: 'README.md' by default
8   */
9  fileName: 'README.md'
10}

❕ NOTE: Please check also the documentation to learn more about configuration.

🧩 EJS template

This library uses EJS 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.

Example:

1/**
2 * .docs/readme/data.js
3 */
4
5// Import package.json data
6const pkg = require('../../package.json')
7const repositoryUrl = pkg.repository.url
8const dependencies = pkg.dependencies || {}
9const devDependencies = pkg.devDependencies || {}
10
11/**
12 * Export data for readme file templating
13 */
14module.exports = {
15  pkg,
16  repositoryUrl,
17  dependencies,
18  devDependencies
19}

Template

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

Example:

1<%# 
2  README.md template
3-%>
4# Awesome project!
5
6👇 **Table of contents:**
7
8<!-- toc -->
9
10## Get started
11
12Clone this [repository](<%= repositoryUrl %>) and install via `npm install`
13
14## Dependencies
15
16<details>
17
18<summary>Global</summary>
19
20<%-
21  await include('common/table.md', {
22    options: [
23      ['name', 'version'],
24      ...(Object.entries(dependencies))
25    ]
26  })
27%>
28
29</details>
30
31<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

1npm run readme

Enjoy! 👍

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

🦾 API

Consult the API documentation

⏫ Migrate from v1

All configuration keys are now optional

The following have been renamed:

• outputName to fileName
• outputPath to destFolder

🧱 Dependencies

Global

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

Dev

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

Peer

name	version

🧪 Next features

• presets ? (GitHub/GitLab)

🤝 Contributing

Please check the contributing guidelines

🎖 License

ISC

---

Made with ❤ by Hervé Perchec

---

README.md - this file was auto generated with @hperchec/readme-generator. Don't edit it.