@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

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

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

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