Un archivo README, junto con una licencia de repositorio y pautas de contribución, te ayudan a comunicar las expectativas y a administrar las contribuciones para tu proyecto.
Un archivo README suele ser el primer elemento que verá un visitante cuando entre a tu repositorio. Los archivos README habitualmente incluyen información sobre:
- Qué hace el proyecto.
- Por qué el proyecto es útil.
- Cómo pueden comenzar los usuarios con el proyecto.
- Dónde pueden recibir ayuda los usuarios con tu proyecto
- Quién mantiene y contribuye con el proyecto.
Si colocas tu archivo README en la raíz de tu repositorio, docs, o en el directorio oculto .github, GitHub Enterprise lo reconocerá y automáticamente expondrá tu archivo README a los visitantes del repositorio.
If you add a README file to the root of a public repository with the same name as your username, that README will automatically appear on your profile page. You can edit your profile README with GitHub Flavored Markdown to create a personalized section on your profile.
Enlaces de sección en los archivos README y las páginas blob
Muchos proyectos usan un índice al comienzo de un archivo README para dirigir a los usuarios a diferentes secciones del archivo. 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:
Enlaces relativos y rutas con imágenes en los archivos README
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 tienes un archivo README en la raíz de tu repositorio y tienes otro archivo en docs/CONTRIBUTING.md, el enlace relativo a CONTRIBUTING.md en tu archivo README podría verse así:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub Enterprise 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. Puedes usar todos los operandos del enlace relativo, 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.