How to read a GitHub README on Android

A README is the Markdown file that introduces a project on GitHub, usually named README.md. To read one on an Android phone you often need nothing new: your browser shows it as a formatted page. If you want the file itself, to read offline or keep, you can download that one file or the whole repository, then open it in a Markdown reader. This guide covers all three.

New to the format? Start with what a .md file is.

Is the browser enough?

Often, yes. Open the repository's page in your phone's browser. GitHub finds a README kept in the repository's main folder, its docs folder or its hidden .github folder, and shows it on that page. You do not need to install anything, and a public repository opens without signing in.

On a narrow screen, the README comes after the project details and the file list, so scroll down until you reach it. On the page we checked at phone width, wide content ran past the right edge of the screen.

There is one limit to know about. GitHub cuts a README off after 500 KiB, so a very long one may not show to the end. And the page needs a connection each time you open it.

Can I use the GitHub app instead?

You can try it. GitHub Mobile is available for Android, and GitHub's documentation says you can use it to browse repositories. That documentation does not describe how READMEs look in the app, so the simple test is to open a repository you care about and see whether it suits you. If you already use the app, this may be all you need.

How do I get just the README file?

Downloading one file is the quickest way to keep a README. GitHub's documentation gives these steps:

  1. Open the repository and tap README.md in the file list.
  2. At the upper right of the file view, tap Raw to see the plain text, or the Download raw file icon to save it.

These buttons can be hard to reach on a phone. We confirmed they are on the page, but at phone width that part of the page can run off the screen, so you may need to scroll sideways.

If you cannot find them, type the file's raw address yourself. Swap in the owner, repository and branch names:

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

This address returns the file as plain text. A repository whose main branch has another name needs that name in place of main.

When should I download the whole repository?

Download the whole repository when the README depends on other files. A README often points to pictures and other documents with relative links, which means paths inside the repository. A single downloaded file arrives without them.

GitHub's documentation gives these steps:

  1. Open the repository's main page.
  2. Above the list of files, tap Code.
  3. Tap Download ZIP.

The ZIP is a snapshot of the files without the project's history, which is all you need for reading. You then have to unpack it. Your phone's file manager may be able to do that. If it cannot, you will need an app that can.

How do I read the .md file after downloading it?

Opened as plain text, the file shows its Markdown symbols: # for headings, ** for bold and | for tables. A Markdown reader turns them into a page. Most readers can open a file in one of two ways:

Look for a reader that draws tables and code blocks, because READMEs use them often. Check how it treats pictures and links too, since those are what you lose with a single downloaded file.

How does PilcrowMD handle a README?

PilcrowMD is our free Markdown reader for Android. It reads GitHub-flavoured Markdown, including tables, task lists and callouts, and it needs no account. Tap Open file on its welcome screen, or choose it under Open with in your file manager.

A few things work differently from the GitHub page:

For more, see Markdown syntax in one page and how to read Markdown privately and offline.

Also on Mac: PilcrowMD for Mac (beta)