Comment lire un README GitHub sur Android

Un README est le fichier Markdown qui présente un projet sur GitHub, généralement nommé README.md. Pour en lire un sur un téléphone Android, tu n’as souvent besoin de rien de nouveau : ton navigateur l’affiche comme une page mise en forme. Si tu veux le fichier lui-même, pour le lire hors ligne ou le conserver, tu peux télécharger ce seul fichier ou tout le dépôt, puis l’ouvrir dans un lecteur Markdown. Ce guide couvre les trois cas.

Le format est nouveau pour toi ? Commence par ce qu’est un fichier .md.

Le navigateur suffit-il ?

Souvent, oui. Ouvre la page du dépôt dans le navigateur de ton téléphone. GitHub trouve un README placé dans le dossier principal du dépôt, dans son dossier docs ou dans son dossier caché .github, et l’affiche sur cette page. Tu n’as rien à installer, et un dépôt public s’ouvre sans connexion.

Sur un écran étroit, le README vient après les informations du projet et la liste des fichiers : faites défiler jusqu’à lui. Sur la page que nous avons vérifiée, à la largeur d’un téléphone, un contenu large dépassait le bord droit de l’écran.

Il y a une limite à connaître. GitHub tronque un README au-delà de 500 KiB, donc un README très long peut ne pas s’afficher jusqu’à la fin. Et la page demande une connexion à chaque ouverture.

Puis-je utiliser plutôt l’application GitHub ?

Tu peux essayer. GitHub Mobile est disponible pour Android, et la documentation de GitHub indique qu’on peut s’en servir pour parcourir les dépôts. Cette documentation ne décrit pas l’aspect des README dans l’application : le plus simple est donc d’ouvrir un dépôt qui t’intéresse et de voir si cela te convient. Si tu utilises déjà l’application, cela peut suffire.

Comment obtenir uniquement le fichier README ?

Télécharger un seul fichier est le moyen le plus rapide de conserver un README. La documentation de GitHub donne ces étapes :

  1. Ouvre le dépôt et touche README.md dans la liste des fichiers.
  2. En haut à droite de la vue du fichier, touche Raw pour voir le texte brut, ou l’icône Download raw file pour l’enregistrer.

Ces boutons peuvent être difficiles à atteindre sur un téléphone. Nous avons confirmé qu’ils sont sur la page, mais à la largeur d’un téléphone cette partie de la page peut dépasser de l’écran, et il te faudra peut-être faire défiler latéralement.

Si tu ne les trouves pas, tape toi-même l’adresse brute du fichier. Remplace le propriétaire, le dépôt et la branche par les tiens :

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

Cette adresse renvoie le fichier en texte brut. Si la branche principale d’un dépôt porte un autre nom, mets ce nom à la place de main.

Quand télécharger tout le dépôt ?

Télécharge tout le dépôt quand le README dépend d’autres fichiers. Un README renvoie souvent vers des images et d’autres documents par des liens relatifs, c’est-à-dire des chemins à l’intérieur du dépôt. Un fichier téléchargé seul arrive sans eux.

La documentation de GitHub donne ces étapes :

  1. Ouvre la page principale du dépôt.
  2. Au-dessus de la liste des fichiers, touche Code.
  3. Touche Download ZIP.

Le ZIP est un instantané des fichiers sans l’historique du projet, ce qui suffit pour lire. Tu dois ensuite le décompresser. Le gestionnaire de fichiers de ton téléphone peut peut-être le faire. Sinon, il te faudra une application qui en est capable.

Comment lire le fichier .md après l’avoir téléchargé ?

Ouvert en texte brut, le fichier montre ses symboles Markdown : # pour les titres, ** pour le gras et | pour les tableaux. Un lecteur Markdown les transforme en page. La plupart des lecteurs peuvent ouvrir un fichier de deux façons :

Cherche un lecteur qui dessine les tableaux et les blocs de code, car les README en utilisent souvent. Regarde aussi comment il traite les images et les liens, car c’est ce que tu perds avec un fichier téléchargé seul.

Comment PilcrowMD gère-t-il un README ?

PilcrowMD est notre lecteur Markdown gratuit pour Android. Il lit le Markdown de type GitHub, y compris les tableaux, les listes de tâches et les encadrés, et ne demande aucun compte. Touche Ouvrir un fichier sur son écran d’accueil, ou choisis-le sous Ouvrir avec dans ton gestionnaire de fichiers.

Quelques points fonctionnent différemment de la page GitHub :

Pour aller plus loin, voir la syntaxe Markdown en une page et comment lire du Markdown en privé et hors ligne.

Aussi sur Mac : PilcrowMD pour Mac (bêta)