about-readmes.md

title	About the repository README file
shortTitle	About READMEs
intro	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.
redirect_from	/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
versions	fpt ghes ghec * * *
topics	Repositories

About READMEs

{% data reusables.repositories.about-READMEs %}

For more information about providing guidelines for your project, see {% ifversion fpt or ghec %}AUTOTITLE and {% endif %}AUTOTITLE.

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 hidden .github, root, or docs directory, {% data variables.product.github %} will recognize and automatically surface your README to repository visitors.

If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

When your README is viewed on GitHub, any content beyond 500 KiB will be truncated.

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

Auto-generated table of contents for markdown files

For the rendered view of any Markdown file in a repository, including README files, {% data variables.product.github %} 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="Table of Contents" %} menu icon at the top left of the rendered page.

Section links in markdown files and blob pages

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

For more detailed information about section links, see Section links.

Relative links and image paths in markdown files

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

Wikis

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

Further reading

• AUTOTITLE
• 5 tips for making your {% data variables.product.company_short %} profile page accessible in the {% data variables.product.company_short %} blog {%- ifversion fpt or ghec %}
• AUTOTITLE {%- endif %}