@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.19.0

See also browserslist documentation

Install package via npm

npm install -D @hperchec/readme-generator

Initialize

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:

{
  "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:

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

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

❕ 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:

/**
 * .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:

<%# 
  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

npm 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.