@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

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>

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

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