如何在 Android 上阅读 GitHub README

README 是在 GitHub 上介绍一个项目的 Markdown 文件,通常名为 README.md。要在 Android 手机上阅读它,往往不需要任何新东西:你的浏览器会把它显示为排好版的页面。如果你想得到文件本身,以便离线阅读或保存,可以下载这一个文件或整个仓库,然后用 Markdown 阅读器打开。本指南涵盖这三种方式。

刚接触这种格式?请先看什么是 .md 文件。

用浏览器就够了吗?

通常够了。在手机浏览器中打开仓库页面。GitHub 会找到存放在仓库主文件夹、docs 文件夹或隐藏的 .github 文件夹中的 README,并在该页面上显示它。你不需要安装任何东西,公开仓库无需登录即可打开。

在窄屏幕上,README 排在项目详情和文件列表之后,所以请向下滚动,直到看到它。在我们检查的页面上,以手机宽度显示时,较宽的内容超出了屏幕右边缘。

有一项限制需要了解。GitHub 会在 README 超过 500 KiB 之后将其截断,所以很长的 README 可能无法显示到末尾。而且每次打开该页面都需要联网。

我可以改用 GitHub 应用吗?

可以试试。GitHub Mobile 提供 Android 版,GitHub 的文档说你可以用它来浏览仓库。该文档没有描述 README 在应用中是什么样子,所以最简单的检验方法是打开一个你关心的仓库,看看是否合适。如果你已经在用这款应用,这可能就是你所需要的一切。

如何只获取 README 文件?

下载单个文件是保存 README 最快的方法。GitHub 的文档给出了这些步骤:

  1. 打开仓库,在文件列表中点按 README.md。
  2. 在文件视图的右上角,点按 Raw 查看纯文本,或点按 Download raw file 图标保存它。

这些按钮在手机上可能不太好点到。我们确认它们在页面上,但以手机宽度显示时,页面的那一部分可能超出屏幕,所以你可能需要横向滚动。

如果找不到它们,可以自己输入该文件的 raw 地址。请换成所有者、仓库和分支的名称:

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

这个地址会把文件作为纯文本返回。如果仓库的主分支叫别的名字,就需要用那个名字代替 main。

什么时候应该下载整个仓库?

当 README 依赖其他文件时,请下载整个仓库。README 常常用相对链接指向图片和其他文档,也就是仓库内部的路径。单独下载的一个文件是不带这些的。

GitHub 的文档给出了这些步骤:

  1. 打开仓库的主页面。
  2. 在文件列表上方,点按 Code。
  3. 点按 Download ZIP。

这个 ZIP 是文件的快照,不含项目的历史记录,而阅读只需要这些。之后你需要解压它。你手机的文件管理器可能能够做到。如果不能,你就需要一个能解压的应用。

下载之后如何阅读 .md 文件?

以纯文本方式打开时,文件会显示它的 Markdown 符号:# 表示标题,** 表示粗体,| 表示表格。Markdown 阅读器会把它们变成页面。大多数阅读器可以用两种方式之一来打开文件:

请选择能绘制表格和代码块的阅读器,因为 README 经常用到它们。也要看看它如何处理图片和链接,因为单独下载一个文件时丢失的正是这些。

PilcrowMD 如何处理 README?

PilcrowMD 是我们免费的 Android Markdown 阅读器。它能读取 GitHub 风格的 Markdown,包括表格、任务列表和提示块,并且无需账号。点按起始画面上的打开文件,或在文件管理器的打开方式下选择它。

有几处与 GitHub 页面的工作方式不同:

更多内容,请参阅一页看懂 Markdown 语法和如何私密地离线阅读 Markdown。

Mac 上同样可用: PilcrowMD Mac 版(测试版)