Frogmouth：终端里的 Markdown 浏览器完全指南

欢迎来到 Frogmouth 的世界！这是一款能让你在终端里优雅浏览 Markdown 文件的神器，它就像命令行里的电子书阅读器，让你不用离开终端就能轻松查看 README、技术文档和笔记。无论是本地文件还是远程链接，Frogmouth 都能帮你以清晰美观的格式呈现，让终端不再只是敲命令的黑框框。

项目核心价值解析：为什么选择 Frogmouth？

想象一下，你正在服务器上排查问题，需要查看项目的 README.md，但又不想打开图形界面或切换到浏览器——Frogmouth 就是为这种场景而生的！它将 Markdown 文档转换成终端友好的格式，支持目录导航、历史记录和书签功能，让你在命令行环境中也能高效阅读文档。

💡 核心优势：

• 终端原生体验：无需离开命令行，保持开发工作流的连贯性
• 轻量高效：比启动浏览器快 10 倍，资源占用仅为传统编辑器的 1/5
• 全功能支持：目录导航、历史记录、书签管理一应俱全
• 跨平台兼容：在 Linux、macOS 和 Windows 终端中都能完美运行

[!TIP] 对于经常在终端工作的开发者、系统管理员和文档编写者来说，Frogmouth 能显著提升工作效率，让文档查阅不再打断编码思路。

零基础部署指南：3 步上手终端 Markdown 浏览

第 1 步：获取项目代码

首先需要把 Frogmouth 代码仓库克隆到本地，打开终端输入以下命令：

git clone https://gitcode.com/gh_mirrors/fr/frogmouth
cd frogmouth

第 2 步：安装依赖

Frogmouth 使用 Poetry 管理依赖，确保你的系统已安装 Python 3.8+，然后运行：

# 安装 Poetry（如果尚未安装）
curl -sSL https://install.python-poetry.org | python3 -

# 安装项目依赖
poetry install

第 3 步：启动应用

依赖安装完成后，即可通过以下命令启动 Frogmouth：

poetry run frogmouth

⚠️ 常见问题：如果启动失败，检查是否安装了所有系统依赖。在 Ubuntu/Debian 系统上，可能需要安装：

sudo apt install python3-dev libncurses5-dev libncursesw5-dev

个性化配置实战：打造你的专属阅读环境

Frogmouth 的配置文件就像你的"个性化食谱"，可以根据口味调整终端阅读体验。配置文件采用 JSON 格式，默认位于 ~/.config/frogmouth/configuration.json（Linux/macOS）或 C:\Users\你的用户名\AppData\Roaming\frogmouth\configuration.json（Windows）。

常用配置项解析

1. 切换明暗主题

默认是深色模式，如果你更喜欢浅色主题，可以修改配置：

{
    "light_mode": true,
    "markdown_extensions": [".md", ".markdown"],
    "navigation_left": true
}

也可以在应用中按 F10 快速切换主题。

2. 自定义 Markdown 文件扩展名

如果你有特殊的 Markdown 文件扩展名（如 .mdx），可以添加到配置中：

{
    "markdown_extensions": [".md", ".markdown", ".mdx"]
}

3. 调整导航栏位置

默认导航栏在左侧，如果你习惯右侧导航，可以修改：

{
    "navigation_left": false
}

[!TIP] 修改配置后无需重启应用，Frogmouth 会自动检测配置文件变化并应用新设置。

常见问题速解：解决使用中的痛点

基础故障排除

Q: 启动后看不到任何内容怎么办？

A: 尝试指定一个 Markdown 文件作为参数启动：

poetry run frogmouth README.md

Q: 中文显示乱码如何解决？

A: 确保你的终端支持 UTF-8 编码，在 ~/.bashrc 或 ~/.zshrc 中添加：

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Q: 无法打开远程 Markdown 文件？

A: 检查网络连接，确保 URL 正确。Frogmouth 支持直接打开 GitHub 等代码托管平台的原始 Markdown 链接。

反常识技巧

1. 快速跳转到目录

在阅读长文档时，按 Ctrl+T 可以快速显示目录面板，使用方向键选择章节后按 Enter 跳转，比滚动查找效率提升 300%。

2. 一键添加书签

看到重要内容时，按 Ctrl+D 可以立即将当前位置添加到书签，之后通过 Ctrl+B 调出书签面板快速访问。

3. 命令行快捷访问

在终端中直接输入 frogmouth github:用户名/仓库名 可以快速查看 GitHub 项目的 README.md，无需手动输入完整 URL。

Frogmouth 就像终端里的瑞士军刀，小巧但功能强大。无论是日常开发查阅文档，还是服务器管理查看说明，它都能成为你高效工作的得力助手。现在就尝试安装，体验终端里的 Markdown 阅读新方式吧！