Acerca de los archivos README

Puedes agregar un archivo README a tu repositorio para comentarle a otras personas por qué tu proyecto es útil, qué pueden hacer con tu proyecto y cómo lo pueden usar.

Acerca de los archivos README

Puedes agregar un archivo README a un repositorio para comunicar información importante sobre tu proyecto. El contar con un README, en conjunto con una licencia de repositorio, archivo de citas, lineamientos de contribución y código de conducta, comunica las expectativas de tu proyecto y te ayuda a administrar las contribuciones.

Para obtener más información acerca de cómo proporcionar lineamientos para tu proyecto, consulta la sección "Agregar un código de conducta para tu proyecto" y "Configurar tu proyecto para que tenga contribuciones sanas".

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 lo reconocerá y automáticamente expondrá tu archivo README a los visitantes del repositorio.

Página principal del repositorio github/scientist y su archivo README

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 obtener más información, consulta la sección "Administrar el README de tu perfil".

El archivo de README en tu nombre de usuario/repositorio de nombre de usuario

Índice auto-generado de los archivos README

Para la versión interpretada de cualquier archivo de lenguaje de marcado en un repositorio, incluyendo los archivos README, GitHub generará un índice automáticamente con base en los encabezados de sección. Puedes ver el índice de un archivo README si haces clic en el icono de menú en la parte superior izquierda de la página interpretada.

README con TOC generado automáticamente

El índice auto-generado se habilita predeterminadamente para todos los archivos de lenguaje de marcado de un repositorio, pero puedes inhabilitar esta característica en tu repositorio.

  1. En GitHub, visita la página principal del repositorio.
  2. Debajo de tu nombre de repositorio, da clic en Configuración. Botón de configuración del repositorio
  3. Debajo de "Características", anula la selección Índice. Configuración de TOC automático en los repositorios

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:

Enlace de sección con el archivo README para el repositorio de github/scientist

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 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.

Leer más

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.