用浏览器就够了吗?
通常够了。在手机浏览器中打开仓库页面。GitHub 会找到存放在仓库主文件夹、docs 文件夹或隐藏的 .github 文件夹中的 README,并在该页面上显示它。你不需要安装任何东西,公开仓库无需登录即可打开。
在窄屏幕上,README 排在项目详情和文件列表之后,所以请向下滚动,直到看到它。在我们检查的页面上,以手机宽度显示时,较宽的内容超出了屏幕右边缘。
有一项限制需要了解。GitHub 会在 README 超过 500 KiB 之后将其截断,所以很长的 README 可能无法显示到末尾。而且每次打开该页面都需要联网。
我可以改用 GitHub 应用吗?
可以试试。GitHub Mobile 提供 Android 版,GitHub 的文档说你可以用它来浏览仓库。该文档没有描述 README 在应用中是什么样子,所以最简单的检验方法是打开一个你关心的仓库,看看是否合适。如果你已经在用这款应用,这可能就是你所需要的一切。
如何只获取 README 文件?
下载单个文件是保存 README 最快的方法。GitHub 的文档给出了这些步骤:
- 打开仓库,在文件列表中点按
README.md。 - 在文件视图的右上角,点按 Raw 查看纯文本,或点按 Download raw file 图标保存它。
这些按钮在手机上可能不太好点到。我们确认它们在页面上,但以手机宽度显示时,页面的那一部分可能超出屏幕,所以你可能需要横向滚动。
如果找不到它们,可以自己输入该文件的 raw 地址。请换成所有者、仓库和分支的名称:
https://raw.githubusercontent.com/OWNER/REPO/main/README.md
这个地址会把文件作为纯文本返回。如果仓库的主分支叫别的名字,就需要用那个名字代替 main。
什么时候应该下载整个仓库?
当 README 依赖其他文件时,请下载整个仓库。README 常常用相对链接指向图片和其他文档,也就是仓库内部的路径。单独下载的一个文件是不带这些的。
GitHub 的文档给出了这些步骤:
- 打开仓库的主页面。
- 在文件列表上方,点按 Code。
- 点按 Download ZIP。
这个 ZIP 是文件的快照,不含项目的历史记录,而阅读只需要这些。之后你需要解压它。你手机的文件管理器可能能够做到。如果不能,你就需要一个能解压的应用。
下载之后如何阅读 .md 文件?
以纯文本方式打开时,文件会显示它的 Markdown 符号:# 表示标题,** 表示粗体,| 表示表格。Markdown 阅读器会把它们变成页面。大多数阅读器可以用两种方式之一来打开文件:
- 在应用内部,使用它自己的打开按钮和 Android 的文件选择器。
- 在文件管理器中,点按文件并选择打开方式。
请选择能绘制表格和代码块的阅读器,因为 README 经常用到它们。也要看看它如何处理图片和链接,因为单独下载一个文件时丢失的正是这些。
PilcrowMD 如何处理 README?
PilcrowMD 是我们免费的 Android Markdown 阅读器。它能读取 GitHub 风格的 Markdown,包括表格、任务列表和提示块,并且无需账号。点按起始画面上的打开文件,或在文件管理器的打开方式下选择它。
有几处与 GitHub 页面的工作方式不同:
- 与文件存放在一起的图片会显示在文件中。网络图片绝不会被下载,所以从网上加载图片的 README 会在没有图片的情况下显示。
- 文件之间的链接只对你所添加文件夹内的笔记有效。对于解压后的仓库,请在我的文件夹中添加该文件夹。
- 指向同一文件内标题的链接会跳转到该标题。
更多内容,请参阅一页看懂 Markdown 语法和如何私密地离线阅读 Markdown。
Mac 上同样可用: PilcrowMD Mac 版(测试版)