Correct Format for Entries in an Awesome List: The Complete Style Guide

Every entry in an awesome list must follow the exact pattern - [Title](URL#readme) - Description. using title case, a space-surrounded dash separator, and a capitalized description ending with a period.

Contributing to the sindresorhus/awesome ecosystem requires strict adherence to markdown formatting rules that ensure consistency across thousands of curated lists. The correct format for entries in an awesome list isn't merely a suggestion—it's enforced by the repository's pull_request_template.md and automated awesome-lint checks. Understanding the precise syntax prevents submission rejections and maintains the project's machine-readable standard.

Anatomy of a Valid Awesome List Entry

The Five Required Components

Every line item must contain these elements in exact order:

1. Bullet prefix – A hyphen followed by a single space (- )
2. Project title – The name in title case enclosed in square brackets
3. Repository link – The URL in parentheses ending with #readme
4. Dash separator – A single hyphen surrounded by spaces (-)
5. Description – An objective, one-sentence summary starting with a capital letter and ending with a period, which must not mention the list name itself

Complete Syntax Example

- [Project Name](https://github.com/user/project#readme) - Short, objective description.

Correct vs. Incorrect Entry Examples

Accepted Entry Format

- [Framer](https://github.com/framer/framer#readme) - Prototyping interactive UI designs.

This entry follows all rules specified in pull_request_template.md: the project name uses title case, the URL ends with the required #readme anchor, and the description objectively describes the project without referencing the list category.

Rejected Entry Format

- [iOS](https://github.com/apple/ios) - Resources and tools for iOS development

This example fails for three reasons: the description lacks a trailing period, the URL omits the mandatory #readme suffix, and the description mentions "iOS" (the list name) rather than describing the project objectively. The awesome-lint tool flags these errors automatically.

Common Formatting Pitfalls

• Missing dash separator – Ensure you include - (space-hyphen-space) between the closing parenthesis and the description.
• Lowercase description start – The description must start with a capital letter.
• Missing trailing period – Every description must end with a period to pass linting.
• Incorrect URL format – The repository URL must end with #readme to anchor directly to the documentation.
• Improper title casing – Project names must use title case regardless of the original repository's styling (e.g., awesome swift becomes Awesome Swift).

Where the Rules Are Defined

The formatting requirements are codified in several key files within the sindresorhus/awesome repository:

• pull_request_template.md – Defines the precise entry format and provides concrete examples of accepted and rejected entries. The template explicitly states that "Your entry here should include a short description…" and demonstrates the required pattern.
• awesome.md – Contains the manifesto explaining the purpose of the format and links to the badge and linting guidelines.
• contributing.md – Outlines contribution steps and directs contributors to the template for formatting requirements.
• awesome-lint – The external automated linter enforces dash separators, capitalization, final periods, and proper linking during CI checks.

Summary

• Every entry must start with - [ followed by the title-cased project name and ](#readme) link.
• Use a space-surrounded dash (-) to separate the link from the description.
• Descriptions must be objective, capitalize the first word, end with a period, and never mention the list category name.
• The pull_request_template.md and awesome-lint tool enforce these rules automatically to ensure machine readability.

Frequently Asked Questions

Why must the URL end with #readme?

The #readme anchor ensures that visitors land directly on the project's documentation when clicking the link from the list. According to the pull_request_template.md and the awesome-lint tool, this suffix is mandatory for all repository links to maintain consistency across the awesome ecosystem.

Can I use asterisks instead of hyphens for bullet points?

No. The specification requires entries to start with a hyphen and a single space (- ). The awesome-lint tool specifically checks for this prefix and will reject entries using asterisks or other bullet styles during automated validation.

What happens if my description doesn't end with a period?

The automated awesome-lint tool will flag the entry as improperly formatted during the CI check. Maintainers will request that you append the missing period before merging your pull request, as the trailing period is required for visual consistency across all awesome lists.

Is title case required for project names that are normally lowercase?

Yes. The pull_request_template.md explicitly requires that project names be written in title case, even if the original repository uses lowercase branding. This standardization ensures the list remains easy to scan and visually uniform.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}