Cómo leer un README de GitHub en Android

Un README es el archivo Markdown que presenta un proyecto en GitHub, normalmente llamado README.md. Para leer uno en un teléfono Android a menudo no necesitas nada nuevo: tu navegador lo muestra como una página con formato. Si quieres el archivo en sí, para leerlo sin conexión o conservarlo, puedes descargar ese único archivo o el repositorio entero, y luego abrirlo en un lector de Markdown. Esta guía cubre las tres opciones.

¿Es la primera vez que ves este formato? Empieza por qué es un archivo .md.

¿Basta con el navegador?

A menudo, sí. Abre la página del repositorio en el navegador de tu teléfono. GitHub encuentra un README guardado en la carpeta principal del repositorio, en su carpeta docs o en su carpeta oculta .github, y lo muestra en esa página. No necesitas instalar nada, y un repositorio público se abre sin iniciar sesión.

En una pantalla estrecha, el README aparece después de los detalles del proyecto y la lista de archivos, así que desplázate hacia abajo hasta llegar a él. En la página que comprobamos, con el ancho de un teléfono, el contenido ancho sobresalía por el borde derecho de la pantalla.

Hay un límite que conviene conocer. GitHub corta un README a partir de 500 KiB, así que uno muy largo puede no mostrarse hasta el final. Y la página necesita conexión cada vez que la abres.

¿Puedo usar la app de GitHub en su lugar?

Puedes probarlo. GitHub Mobile está disponible para Android, y la documentación de GitHub dice que puedes usarla para explorar repositorios. Esa documentación no describe qué aspecto tienen los README en la app, así que la prueba sencilla es abrir un repositorio que te interese y ver si te sirve. Si ya usas la app, puede que esto sea todo lo que necesitas.

¿Cómo consigo solo el archivo README?

Descargar un solo archivo es la forma más rápida de conservar un README. La documentación de GitHub da estos pasos:

  1. Abre el repositorio y toca README.md en la lista de archivos.
  2. En la parte superior derecha de la vista del archivo, toca Raw para ver el texto sin formato, o el icono Download raw file para guardarlo.

Estos botones pueden ser difíciles de alcanzar en un teléfono. Confirmamos que están en la página, pero con el ancho de un teléfono esa parte de la página puede salirse de la pantalla, así que puede que tengas que desplazarte hacia los lados.

Si no los encuentras, escribe tú mismo la dirección del archivo sin procesar. Sustituye los nombres del propietario, del repositorio y de la rama:

https://raw.githubusercontent.com/OWNER/REPO/main/README.md

Esta dirección devuelve el archivo como texto sin formato. Un repositorio cuya rama principal tenga otro nombre necesita ese nombre en lugar de main.

¿Cuándo debo descargar el repositorio entero?

Descarga el repositorio entero cuando el README dependa de otros archivos. Un README suele apuntar a imágenes y otros documentos con enlaces relativos, es decir, rutas dentro del repositorio. Un solo archivo descargado llega sin ellos.

La documentación de GitHub da estos pasos:

  1. Abre la página principal del repositorio.
  2. Encima de la lista de archivos, toca Code.
  3. Toca Download ZIP.

El ZIP es una instantánea de los archivos sin el historial del proyecto, que es todo lo que necesitas para leer. Después tienes que descomprimirlo. Puede que el gestor de archivos de tu teléfono pueda hacerlo. Si no puede, necesitarás una app que sí.

¿Cómo leo el archivo .md después de descargarlo?

Abierto como texto sin formato, el archivo muestra sus símbolos de Markdown: # para los títulos, ** para la negrita y | para las tablas. Un lector de Markdown los convierte en una página. La mayoría de los lectores pueden abrir un archivo de dos maneras:

Busca un lector que dibuje tablas y bloques de código, porque los README los usan a menudo. Comprueba también cómo trata las imágenes y los enlaces, ya que eso es lo que pierdes con un solo archivo descargado.

¿Cómo trata PilcrowMD un README?

PilcrowMD es nuestro lector de Markdown gratuito para Android. Lee el Markdown con sabor a GitHub, incluidas las tablas, las listas de tareas y los avisos, y no necesita cuenta. Toca Abrir archivo en su pantalla de bienvenida, o elígelo en Abrir con en tu gestor de archivos.

Algunas cosas funcionan de forma distinta a la página de GitHub:

Para más información, consulta la sintaxis de Markdown en una página y cómo leer Markdown en privado y sin conexión.

También en Mac: PilcrowMD para Mac (beta)