About The Project

This pre-commit hook helps maintain consistent README files by validating that your README.md matches the output generated from your Handlebars template and JSON configuration. It ensures documentation stays up-to-date automatically.

Built With

This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

This is an example of how to list things you need to use the software and how to install them.

• Node.js

  npm install npm@latest -g

• Pre-commit

  npm install -g pre-commit

Installation

Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services.

1. Add this to your .pre-commit-config.yaml:

   repos:
     - repo: https://github.com/actuarysailor/pre-commit-readme-generator
       rev: v0.0.0<!-- x-release-please-version -->
       hooks:
         - id: readme-generator-test

2. Clone the repo (if contributing)

   git clone https://github.com/actuarysailor/pre-commit-readme-generator.git

3. Install NPM packages

   npm install

4. Create your configuration file

   {
     "project": {
       "title": "Your Project Name",
       "description": "Your project description"
     }
   }

5. Generate your README

   node src/generator.js your-config.json README.md templates/default.hbs

Usage

Add the hooks to your .pre-commit-config.yaml in this order (generate first, validate last):

repos:
  - repo: https://github.com/actuarysailor/pre-commit-readme-generator
    rev: v1.0.0  # Use the ref you want to point at
    hooks:
      - id: readme-generator-update   # Generates/updates README.md from template/config
      # ... other hooks (linters, formatters, etc.) ...
      - id: readme-generator-validate # Fails if README.md (or any file) has uncommitted changes

Available Hooks

• readme-generator-update: Generates or updates your README.md from the template and configuration
• readme-generator-validate: Fails if README.md (or any file) has uncommitted changes (does not generate or update)
• file-validate-no-diff: General-purpose file validation for any file(s)

Repository Structure

Your repository should have:

• BLANK_README.md - Handlebars template
• configs/example.json - Configuration file
• README.md - Generated output

The update hook will generate or update README.md from the template and config. The validate hook will ensure it is committed and unchanged after all other hooks run.

For more examples, please refer to the Documentation

Roadmap

• [ ] Add support for multiple template formats
  • [ ] Mustache templates
  • [ ] Liquid templates
• [ ] Enhanced validation options
• [ ] Custom helper functions
• [x] Automated releases and changelog generation
• [ ] Multi-language documentation support
• [ ] Automatic code documentation extraction
  • [ ] Terraform/OpenTofu resource documentation
  • [ ] API endpoint documentation from code
  • [ ] Function/method signature extraction
  • [ ] Dependency analysis and documentation
  • [ ] Output schema documentation
• [ ] Advanced integrations
  • [ ] Docker image documentation
  • [ ] GitHub Actions workflow documentation
  • [ ] Database schema documentation

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors

License

Distributed under the MIT License. See LICENSE for more information.

Contact

| | | |:---:|:---| | | your-display-name-or-handle | | 📧 | [email protected] | | 🐙 | @actuarysailor |

Project Link: https://github.com/actuarysailor/pre-commit-readme-generator

Acknowledgments

Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off!

• Best-README-Template
• Handlebars.js
• Pre-commit Framework
• Choose an Open Source License
• GitHub Pages