MD文件阅读器用户手册

手册版本：2026-08 适用版本：MD文件阅读器 1.5.0 适用对象：第一次使用本应用阅读、管理、导出或轻量编辑 Markdown 文档的用户

1. 认识 MD文件阅读器

MD文件阅读器（MDViewer）是一款以“本地 Markdown 阅读”为主的 Android 应用，适合查看：

• README、项目说明、接口文档
• 学习笔记、知识库、会议纪要
• 从微信、QQ、浏览器、网盘或文件管理器收到的 .md 文件
• 带表格、代码块、链接、图片、目录、任务列表或数学公式的技术文档

应用以阅读体验为主，同时提供本地仓库、最近打开、文件管理、搜索、主题与字体、长图/PDF 导出、复制富文本、轻量编辑和可选的 Git 云同步功能。

本应用不是完整的 Markdown 写作工作台，更适合阅读现有文档、创建简单笔记和进行小范围修改。

2. 首次使用与文件权限

首次启动时，请先阅读并同意隐私政策。部分 Android 版本随后还会要求文件访问权限：

• 如果其他应用通过系统内容 URI 提供文件，MD文件阅读器会优先使用该系统授权。
• Android 10 及以下系统可能要求读取或写入外部存储权限。
• Android 11 及以上系统打开 /storage/emulated/0 等直接文件路径时，可能要求允许“管理所有文件”。
• 权限只用于读取、管理或保存你主动打开的文件，不会后台扫描全部文件，也不会上传文档内容。

从应用首页进入“手机存储”时，会使用 Android 系统文件选择器。系统可能只授权当前文件；如果授权不能长期保留，应用重启后可能需要重新选择。

3. 首页与三个文件入口

应用首页默认显示“本地仓库”。点击页面左上方的下拉箭头，可以在以下入口之间切换：

最近打开

显示最近阅读过的文件。点击条目可继续阅读；如果文件已经移动、删除或授权失效，应用会提示重新选择。

最近打开列表中的文件可以来自本地仓库，也可以来自系统文件选择器或其他应用。

本地仓库

本地仓库是应用管理文档的主要目录，适合长期保存笔记、图片和附件。首次使用时，应用会在这里放入用户手册、微信打开步骤和 Gitee 云仓库说明。

本地仓库中的文件可以直接重命名、复制、移动、删除和同步到 Git 仓库。

手机存储

点击“手机存储”会打开 Android 系统文件选择器。可选择 Markdown、常见文本、CSV、JSON 和常见图片文件。

PDF、压缩包及音视频文件不属于当前阅读范围。选择不支持的文件时，应用会给出提示。

4. 打开外部 Markdown 文件

从文件管理器打开

1. 打开手机文件管理器。
2. 找到 .md 或 .markdown 文件。
3. 点击文件。
4. 在打开方式中选择“MD文件阅读器”。

从微信或 QQ 打开

1. 在聊天中点开收到的 Markdown 文件。
2. 选择“其他应用打开”或类似入口。
3. 选择“MD文件阅读器”。

如果聊天软件中暂时看不到本应用，建议先把文件保存到手机，再通过系统文件管理器或首页“手机存储”打开。

收录到本地仓库

从微信、文件管理器或手机存储打开外部文件后，阅读页顶部可能出现“收录到本地仓库”按钮。

点击后，应用会：

1. 将当前文件复制到本地仓库。
2. 遇到同名文件时自动生成不冲突的文件名，不覆盖原文件。
3. 切换到本地仓库中的副本继续阅读。
4. 如果已开启 Git 云同步，安排同步这份新文件。

已经位于本地仓库中的文件不会重复显示该按钮。

外部文件的常见限制

• 只读来源不能直接编辑或重命名。
• 系统只授权当前文件时，同目录图片等相对资源可能无法显示。
• 授权失效后，可在“最近打开”中点击“重新选择”恢复访问。
• 需要长期保存和编辑的文件，建议先收录到本地仓库。

---

5. 管理本地仓库

浏览文件夹

页面标题区会显示当前位置，例如：

本地仓库 > 项目资料 > 接口文档

点击面包屑中的上级目录可以快速返回。点击文件夹进入下一级，按系统返回键回到上一级。

新建文件夹、搜索和排序

本地仓库顶部操作栏提供：

• 新建文件夹
• 搜索当前仓库中的文件
• 选择排序方式

创建笔记

点击底部“创建笔记”，应用会在本地仓库根目录创建真实文件并直接进入编辑模式。

文件名按顺序自动生成：

• 笔记001.md
• 笔记002.md
• 笔记003.md

如果已有同名文件，应用会继续查找下一个可用编号。

单个文件或文件夹操作

点击条目右侧的 More 按钮，可使用：

• 重命名
• 复制
• 移动
• 文件信息
• 删除

删除会操作实际文件，请确认后再继续。

批量选择

长按文件或文件夹进入选择状态。选中一个或多个条目后，顶部会显示复制、移动、文件信息和删除等可用操作；“文件信息”只在选中单个条目时显示。

---

6. 最近打开与文件清理

在首页入口菜单中选择“最近打开”，可以重新进入最近阅读过的文件。

点击文件条目右侧的操作入口，可根据文件来源使用：

• 重命名
• 删除
• 文件信息
• 从最近移除

系统 URI 文件是否支持重命名或删除，取决于来源应用授予的权限。“从最近移除”只清理最近记录，不删除原文件。

点击右上角 More 菜单中的“文件清理”，可以批量选择最近文件：

• 本地文件会从存储中实际删除。
• 系统 URI 条目会从最近记录中移除。
• 删除后无法通过应用恢复，请提前确认文件是否仍需要。

---

7. 首页底部操作栏

首页底部固定提供三个入口：

创建笔记

创建新的编号笔记并直接进入编辑模式。

同步仓库

• 尚未配置 Git 云同步时：打开 Git 云同步配置页。
• 已开启 Git 云同步时：立即执行一次同步。

同步过程中，首页会显示当前分支和同步状态。

工具箱

工具箱功能仍在建设中。当前可从提示窗口直接进入意见反馈，提交希望加入的工具或使用建议。

8. 阅读页基础操作

打开文档后会进入阅读页。

返回

点击左上角返回按钮回到上一页。对于从其他应用打开的文件，返回后会进入应用的“最近打开”页面。

标题、目录与重命名

点击顶部文件标题可以打开目录。目录根据文档中的 #、##、### 等标题生成。

在目录窗口中可以：

• 点击标题跳转到对应位置。
• 点击“重命名”修改当前本地文件名。
• 点击关闭按钮退出目录。

只读文件或不具备真实本地路径的文件可能无法重命名。

搜索

点击阅读页右上角 More 菜单，选择“搜索”，输入关键词后可在匹配结果之间切换。

退出搜索时，页面会返回正常阅读状态。

文档内链接

点击网页链接会交给系统浏览器处理。文档中的相对 Markdown 文件链接会优先在应用内打开；相对图片会从当前文档所在目录解析。

在浏览模式和阅读模式中，双击图片可进入全屏大图；单击图片不会打开全屏，以减少阅读时误触。

9. 阅读模式中的任务框

对于可写的本地文档，阅读模式下的 Markdown 任务框可以直接点击：

- [ ] 待办事项
- [x] 已完成事项

点击任务框后，勾选状态会先保留在当前阅读会话中。之后可以：

• 点击“编辑”，再点击保存按钮写入文件。
• 直接退出阅读页，并在“未保存的更改”提示中选择保存。

只读文件和临时草稿中的任务框不能直接修改。

10. 轻量编辑与保存

进入编辑模式

点击浏览页顶部的“编辑”按钮，进入带格式编辑模式。文档在同一张排版画布中即时修改和预览，底部可滑动工具栏提供：

• 任务框
• 粗体
• 斜体
• 下划线
• 删除线
• 有序列表
• 无序列表
• 引用
• 链接
• 代码块

标题、正文、引用、列表、任务框、链接和代码可直接修改。图片、表格、公式、脚注、前置内容和原始 HTML 等复杂块会以只读方式显示；点击后可转到“源代码模式”并定位到对应内容。

需要精确修改 Markdown 语法时，在更多菜单中选择“源代码模式”。两种编辑模式共用一份未保存草稿，往返切换不会写入原文件。

粘贴聊天回答

从豆包等聊天应用复制带标题、列表、链接、代码块或表格的回答后，在新建笔记的编辑画布长按并选择“粘贴”。当来源应用向系统剪贴板提供 HTML 或带样式文本时，应用会转换为可编辑的 Markdown 排版内容；如果来源应用只提供纯文本，则保持原文粘贴。表格等复杂内容会作为只读块保留。

如果只需要文字，请选择系统的“粘贴为纯文本”。图片附件不会自动下载或保存到笔记中，图片说明文字会保留。

保存与返回浏览模式

编辑模式下：

• 点击顶部保存按钮，将内容立即写入文件。
• 点击顶部“浏览模式”按钮或按 Android 返回键，返回渲染后的浏览页面。
• 从编辑切换到浏览时不会写入原文件；未保存内容会继续用于当前预览。
• 未保存内容会在设备的应用私有空间保留恢复草稿，不会上传；保存或明确丢弃后会删除，孤立草稿最长保留 7 天。
• 如果保存时检测到原文件已被其他应用修改，应用会停止覆盖并创建冲突副本，再以源代码模式打开。

退出时处理未保存内容

如果内容有变化但尚未保存，退出阅读页时会出现“未保存的更改”提示，可以选择：

• 保存
• 放弃更改
• 取消退出

11. 阅读设置、主题、字体和字号

在阅读页右上角 More 菜单中点击“阅读设置”，会从底部打开设置面板。

主题样式

当前内置主题包括：

• 默认
• GitHub 浅色
• GitHub 深色
• 纸张
• 极简
• 科技蓝

主题会同时影响屏幕阅读和导出效果。

阅读模式

浏览模式保持原有的连续滚动，编辑模式也不会改变。需要像电子书一样阅读时，点击右上角编辑按钮旁的书本图标；进入后会隐藏编辑按钮，可左右滑动或点按页面左右两侧翻页，页面底部会显示当前页和总页数。点击右上角的浏览图标即可退出阅读模式并恢复连续滚动；退出编辑模式也使用相同的浏览图标。代码块、宽表格和较长公式仍可在内容区域内横向查看。

阅读字体

当前可选字体包括：

• 系统字体
• 霞鹜文楷
• Noto Serif SC
• Noto Sans SC
• 站酷小薇体
• 马善政毛笔楷书

除系统字体外，字体会在首次选择时按需下载、校验并缓存在应用内部。下载失败时，请检查网络后重试。

字号

点击字号两侧的 A⁻、A⁺ 按钮即可逐级调整当前文档的显示字号，阅读页面会立即刷新。点击右侧字体名称，会从底部打开字体选择抽屉；未下载的字体也会先显示真实字形预览。

看视频去广告

完整观看激励视频后，当天不再显示 Banner 和信息流广告。广告权益按本地日期计算，次日恢复。

12. 分享、导出与复制富文本

在浏览模式下，点击阅读页右上角 More 菜单，再点击“分享”；在阅读模式下，点击底部栏中位于“目录”左侧的“分享”。两处入口都会显示当前文档支持的输出方式：

导出 md 原文件

将当前 Markdown 文件原样分享给其他应用。通过只读内容 URI 打开的文档可能不显示此选项。

导出长图

将当前渲染效果生成 PNG 长图并调起系统分享面板。文档过长时，应用会提示改用“导出 PDF”。

导出 PDF

将当前渲染效果生成 PDF 并调起系统分享面板，更适合长文档和分页保存。

复制富文本格式到剪贴板

将 Markdown 转换为 HTML 富文本后写入剪贴板，适合粘贴到公众号编辑器或其他支持富文本的编辑框。

不同编辑器对剪贴板 HTML 的处理存在差异。如果粘贴效果异常，可以更换主题后重新复制，或在“用户设置”中开启剪贴板诊断后提交反馈。

导出来源尾注

长图和 PDF 默认会带有 MD文件阅读器来源尾注。可在“用户设置”中完整观看激励视频，去除当天导出文件的来源尾注。

13. 用户设置

在首页右上角 More 菜单中点击“用户设置”，可以配置：

• 主题样式：设置默认阅读主题。
• 阅读字体：设置默认阅读字体。
• 字号：调整编辑器中的文字大小。
• 关闭广告：观看激励视频后关闭当天的 Banner 和信息流广告。
• 去除导出文件来源尾注：观看激励视频后去除当天导出文件的来源尾注。
• 显示剪贴板诊断：用于排查富文本复制问题。
• 版本管理与 Git 云同步：管理本地文件版本、已删除文件恢复、仓库关联和自动同步。

阅读页中的主题、字体和字号设置会直接作用于当前文档；首页“用户设置”更适合提前调整默认偏好。

14. 文件版本管理与 Git 云同步（可选）

本地版本管理和 Git 云同步都默认关闭。只开启本地版本管理时，历史保存在手机“文档”目录，不会上传；需要跨设备备份时，再配置自己的私有 Gitee、GitHub 或其他 HTTPS Git 仓库。

本地版本管理

1. 进入“版本管理与 Git 云同步”，开启“本地版本管理”。
2. 首次开启会把当前文档记录为基线。
3. 保存、新建、删除、重命名、移动或导入文件后，连续两分钟没有新变化时形成自动版本。
4. 在阅读页或文件列表的文件操作菜单中选择“版本历史”，可预览、逐行比较和恢复。
5. 需要标记重要节点时，在文件历史页点击“创建版本”并填写备注。

恢复前会先保存当前内容，恢复操作本身也会成为新版本。“已删除文件”入口可以找回仍存在于历史中的文件。关闭本地版本管理只停止记录，不会删除已有历史。

配置仓库

1. 在首页右上角 More 菜单中点击“版本管理与 Git 云同步”，也可以从“用户设置”进入。
2. 开启“Git 云文件管理”。
3. 选择 Git 服务：Gitee、GitHub 或其他 HTTPS Git。
4. 填写 HTTPS 仓库地址、Git 用户名、访问令牌和分支。
5. 点击“测试并保存”；如果只想验证参数，可点击“仅测试连接”。
6. 本地和远端都有文件时，按提示选择首次同步方向。
7. 根据需要开启“本地变更后及每日自动同步”和“自动同步仅使用 Wi-Fi”。

GitHub 建议使用只授权目标仓库、具备 Contents 读写权限的 fine-grained personal access token。令牌作为 HTTPS 密码使用。

日常同步

开启后：

• 保存、新建、重命名或删除本地仓库内容后，会安排自动同步。
• 开启每日自动同步后，应用会进行补偿同步。
• 点击首页底部“同步仓库”可立即同步。
• 配置页还可执行立即同步、查看高级仓库提交记录和解除关联。

冲突处理

同一个文件在本地和远端同时修改时，应用会保留主版本，并把另一版本放入“冲突副本”目录，不会直接丢弃内容。

首次关联时未被选为主版本的一方，也会保留为冲突副本，便于手动比较和整理。

使用限制

• 请优先使用私有仓库，并只授予访问令牌必要权限。
• Gitee 预设会阻止同步超过 45 MB 的单个文件，仓库检查上限为 450 MB。
• GitHub 预设会阻止同步超过 95 MiB 的单个文件，仓库检查上限为 1 GiB。
• 当前不支持 Git LFS。
• 本地版本管理支持 Android 5.0 或更高版本；Git 云同步需要 Android 6.0 或更高版本。
• 解除关联会清除访问令牌和远端配置，但保留本地文档及本地版本历史。

如需详细说明，请打开本地仓库中的《如何使用文件版本管理》和《如何集成Gitee云仓库》。

15. Markdown 支持范围

MD文件阅读器支持常见 Markdown 内容，包括：

• 标题、段落、引用
• 无序列表、有序列表、任务列表
• 表格
• 代码块与行内代码
• 链接、图片
• 脚注、提示块等常见扩展语法
• 文档目录
• 数学公式

数学公式使用内置本地 KaTeX 资源渲染，常见行内公式和块级公式都可以显示。

行内公式：$E = mc^2$

块级公式：$$\int_{0}^{1} x^{2},dx = \frac{1}{3}$$

不同 Markdown 编辑器对扩展语法的支持不完全一致。如果文档大量依赖特殊语法，显示效果可能和原编辑器略有差异。

16. Markdown 基础速查

标题

# 一级标题
## 二级标题
### 三级标题

列表

- 无序列表
- 第二项

1. 有序列表
2. 第二项

任务列表

- [ ] 待办事项
- [x] 已完成事项

强调

**加粗**
*斜体*
~~删除线~~
`行内代码`

链接与图片

[打开网站](https://example.com)

![示意图](images/demo.png)

代码块

```python
print("hello markdown")
```

17. 意见反馈、关于与更新

意见反馈

在首页右上角 More 菜单中点击“意见反馈”。请选择问题反馈或功能建议，并填写标题、详细描述；邮箱和微信为选填。

提交时会附带 App 版本、Android 版本、设备型号、来源页面等基础环境信息，用于定位问题。应用不会自动上传正在阅读的文档、截图或任意文件。

如果在线反馈服务暂不可用，页面会显示微信和邮箱联系方式。

关于与开源许可

“关于”页面会显示当前版本、检查更新入口、应用说明和开源许可入口。第三方开源许可可在应用内直接查看。

检查更新

应用在启动后会检查更新，但不会无提示地直接安装。

发现新版本后：

• 首页右上角 More 图标会显示红点。
• “关于”菜单项会显示红点。
• 关于页版本号旁边也会显示红点。

在关于页点击“检查更新”，按提示下载或跳转应用商店。部分渠道安装下载版更新时，系统可能要求允许本应用安装未知来源应用。

18. 常见问题

打不开 Markdown 文件

可能原因：

• 文件尚未下载完成。
• 文件扩展名或类型不受支持。
• 来源应用没有提供可读取的路径或内容 URI。
• Android 系统尚未授予文件访问权限。

建议先保存到手机，再通过首页“手机存储”选择；如需长期使用，再收录到本地仓库。

最近打开中的文件无法访问

原文件可能已经移动、删除，或系统授权已经失效。点击“重新选择”，重新定位同一文件即可更新最近记录。

文档中的图片不显示

请检查图片链接是否正确。相对图片依赖当前文档所在目录；如果系统只授权单个外部文件，应用可能无法读取同目录图片。建议把 Markdown 和图片一起放入本地仓库。

无法编辑、重命名或删除

当前文件可能来自只读 URI，或来源应用没有授予写入权限。可先使用“收录到本地仓库”，再修改本地副本。

切回阅读模式后修改没有写入文件

“浏览模式”只切换到阅读预览，不会自动保存。请在编辑模式点击保存；如果直接退出，应用会提示是否保存未保存内容。

长图导出失败或提示文档过长

长图受设备内存和图片像素限制。请改用“导出 PDF”，或减少文档中的超大图片。

数学公式没有按预期显示

请确认公式语法完整，常见写法为 $...$ 或 $$...$$。特别复杂的 LaTeX 宏可能无法完整显示。

粘贴到公众号后格式不一致

不同编辑器对剪贴板 HTML 的解析不同。可切换主题后重新“复制富文本格式到剪贴板”；仍有问题时，开启剪贴板诊断并提交反馈。

首页或关于菜单出现红点

红点表示检测到可用新版本。进入“关于”，点击版本号后的“检查更新”即可。

Git 同步失败

依次检查：

• 仓库地址是否为完整 HTTPS 地址。
• 用户名、访问令牌和分支是否正确。
• 令牌是否拥有目标私有仓库的读写权限。
• 是否存在超过当前服务限制的大文件。
• 手机网络是否能访问对应 Git 服务。

---

19. 推荐使用流程

阅读外部文件

收到 Markdown 文件 -> 用 MD文件阅读器打开 -> 搜索/目录定位 -> 需要长期保存时收录到本地仓库

创建和维护笔记

首页创建笔记 -> 使用格式工具栏编辑 -> 保存 -> 需要时导出长图/PDF或复制富文本

多设备备份

准备私有 Git 仓库 -> 配置 Git 云同步 -> 首次选择同步方向 -> 日常自动同步并定期检查版本历史

使用建议：

• 重要外部文件先收录到本地仓库。
• 长文档优先使用目录和搜索。
• 编辑后点击保存，不要只切换到浏览模式。
• 重要文档修改前后各同步一次。
• 导出公众号内容时，先选择合适主题和字体，再复制富文本或导出长图。