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 and contribution guidelines, communicates expectations for your project and helps you manage contributions.
For more information about providing guidelines for your project, see "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 hidden .github, root, or docs directory, GitHub Enterprise Server 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.
Si agregas un archivo de README a la raíz de un repositorio público con el mismo nombre que tu nombre de usuario, dicho README aparecerá automáticamente en tu página de perfil. Puedes editar el README de tu perfil con el Marcado Enriquecido de GitHub para crear una sección personalizada en tu perfil. Para más información, vea "Administración del archivo Léame del perfil".
Auto-generated table of contents for README files
For the rendered view of any Markdown file in a repository, including README files, GitHub Enterprise Server 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 menu icon at the top left of the rendered page.
Section links in README files and blob pages
Puedes vincular directamente a una sección en un archivo expedido si deslizas el puntero sobre el encabezado de la sección para exponer el enlace:
Relative links and image paths in README files
Puedes definir enlaces relativos y rutas de imagen en los archivos representados para ayudar a que los lectores naveguen hasta otros archivos de tu repositorio.
Un enlace relativo es un enlace que es relativo al archivo actual. Por ejemplo, si tiene un archivo Léame en la raíz del repositorio y tiene otro archivo en docs/CONTRIBUTING.md, el vínculo relativo a CONTRIBUTING.md en el archivo Léame podría tener este aspecto:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub Enterprise Server transformará de manera automática el enlace relativo o la ruta de imagen en cualquier rama en la que te encuentres actualmente, de modo que el enlace o ruta siempre funcione. La ruta de acceso del vínculo será relativa al archivo actual. Los vínculos que comienzan por / serán relativos a la raíz del repositorio. Puede usar todos los operandos de vínculo relativos, como ./ y ../.
Los enlaces relativos son más sencillos para los usuarios que clonan tu repositorio. Puede que los enlaces absolutos no funcionen en los clones de tu repositorio. Recomendamos usar enlaces relativos para consultar los archivos dentro de tu repositorio.
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."