Skip to content

Badges

A badge is a simple embeddable icon that displays various metrics such as the number of stars or forks for a repository, languages used in the project, CI/CD build status, test coverage, the license of the project, and more. Badges are a great way to provide quick information about your project to users and visitors.

README-AI offers various badge styles to enhance your project's README. This guide explains how to use and customize these badges.

Badge Styles

Use the --badge-style option to select from the following styles:

Default Badge Default Badge Default Badge Default Badge

Flat Badge

Flat-Square Badge

For-the-Badge Badge

Plastic Badge

Skills Badge

Skills-Light Badge

Social Badge

How It Works

README-AI automatically detects your project's dependencies and technologies during the repository ingestion process. It then uses these dependencies and technologies to generate a comprehensive list of relevant badges for your project.

When you provide the --badge-style option to the readmeai command, two sets of badges are generated:

  1. Default Metadata Badges: The default set is always included in the generated README file. The default badges include the project license, last commit, top language, and total languages.
  2. Project Dependency Badges: When the --badge-style argument is provided to the CLI, a second badge set is generated, representing the extracted dependencies and metadata from your codebase.

The badge sets are formatted in the README header and provide the reader with a quick overview of the project's key metrics and technologies.

Usage

Let's generate a README with custom badge colors and styles using the --badge-color and --badge-style options:

readmeai --badge-color orange \
         --badge-style flat-square \
         --repository https://github.com/eli64s/readme-ai

The command above generates a README with the following badge configuration:

Example

License Last Commit Top Language Language Count

Built with the tools and technologies:

pre-commit Ruff GNU Bash Pytest Docker Python GitHub Actions Poetry AIOHTTP Material for MkDocs OpenAI Google Gemini Pydantic

The --badge-color option only modifies the default badge set, while the --badge-style option is applied to both the default and project dependency badges

Tips for Using Badges

  • Choose a badge style that complements your project's overall design.
  • Use badges to highlight relevant information about your project, such as license, build status, and test coverage.
  • Don't overuse badges – too many can clutter your README and make it hard to read.
  • Ensure that all badge links are correct and up-to-date.
  • Consider using custom badges for project-specific information or metrics.

References

Thank you to the following resources for providing open-source badges and icons: