docs/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md

title, intro, redirect_from, versions, topics

title	intro	redirect_from	versions	topics
About READMEs	You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it.	/articles/section-links-on-readmes-and-blob-pages /articles/relative-links-in-readmes /articles/about-readmes /github/creating-cloning-and-archiving-repositories/about-readmes /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-readmes	fpt ghes ghae ghec * * * *	Repositories

About READMEs

You can add a README file to a repository to communicate important information about your project. A README, along with a repository license{% ifversion fpt or ghes > 3.2 or ghae-issue-4651 or ghec %}, citation file{% endif %}{% ifversion fpt or ghec %}, contribution guidelines, and a code of conduct{% elsif ghes %} and contribution guidelines{% endif %}, communicates expectations for your project and helps you manage contributions.

For more information about providing guidelines for your project, see {% ifversion fpt or ghec %}"Adding a code of conduct to your project" and {% endif %}"Setting up your project for healthy contributions."

A README is often the first item a visitor will see when visiting your repository. README files typically include information on:

• What the project does
• Why the project is useful
• How users can get started with the project
• Where users can get help with your project
• Who maintains and contributes to the project

If you put your README file in your repository's root, docs, or hidden .github directory, {% data variables.product.product_name %} will recognize and automatically surface your README to repository visitors.

{% ifversion fpt or ghes or ghec %}

{% data reusables.profile.profile-readme %}

{% endif %}

{% ifversion fpt or ghae or ghes > 3.1 or ghec %}

Auto-generated table of contents for README files

For the rendered view of any Markdown file in a repository, including README files, {% data variables.product.product_name %} will automatically generate a table of contents based on section headings. You can view the table of contents for a README file by clicking the {% octicon "list-unordered" aria-label="The unordered list icon" %} menu icon at the top left of the rendered page.

{% endif %}

Section links in README files and blob pages

{% data reusables.repositories.section-links %}

Relative links and image paths in README files

{% data reusables.repositories.relative-links %}

Wikis

A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis. For more information, see "About wikis."

Further reading

• "Adding a file to a repository"
• 18F's "Making READMEs readable"