Frogmouth终端Markdown浏览器全流程使用指南

快速部署Frogmouth终端工具

🔍 本节重点：从源码到运行的3步安装法

想要在终端里优雅地浏览Markdown文件？Frogmouth让这一切变得简单！只需三个步骤，即可完成从代码获取到应用启动的全过程：

1. 克隆项目代码
   打开终端执行以下命令，将项目代码下载到本地：

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

2. 安装依赖环境
   项目使用Poetry管理依赖，执行以下命令完成环境配置：

   poetry install
   

3. 启动应用程序
   通过Python直接运行主程序：

   poetry run python -m frogmouth
   

❓ 常见问题：

• 提示"Poetry: command not found"？先执行pip install poetry安装依赖管理工具
• 依赖安装失败？检查Python版本是否≥3.8，推荐使用3.10及以上版本

探索核心功能模块架构

🔍 本节重点：理解项目目录结构与功能分布

Frogmouth采用模块化设计，核心代码组织在frogmouth/目录下，主要包含五大功能模块：

• 应用核心（frogmouth/app/）
  包含应用入口和主控制器，其中app.py是程序启动的总调度中心

• 数据管理（frogmouth/data/）
  处理书签（bookmarks.py）、历史记录（history.py）和配置信息（config.py）

• 交互界面（frogmouth/widgets/）
  提供终端UI组件，如导航面板（navigation_panes/）、地址栏（omnibox.py）和内容查看器（viewer.py）

• 弹窗系统（frogmouth/dialogs/）
  实现各类交互对话框，包括错误提示（error.py）、输入框（input_dialog.py）等

• 工具函数（frogmouth/utility/）
  提供广告管理（advertising.py）和类型检测（type_tests.py）等辅助功能

❓ 常见问题：

• 如何查看模块间依赖关系？执行poetry show --tree查看依赖树
• 想修改默认配置？配置文件位于frogmouth/data/config.py

掌握终端交互操作技巧

🔍 本节重点：常用快捷键与功能调用方法

启动Frogmouth后，这些实用操作能帮你高效浏览Markdown文档：

1. 基础导航

   • Tab键：在导航面板与内容区之间切换
   • ↑↓箭头：滚动浏览内容
   • q键：退出应用

2. 地址栏操作

   • 按下/键激活地址栏，输入本地文件路径（如./README.md）
   • 支持自动补全功能，按Tab键补全路径

3. 书签管理

   • 在浏览文件时按b添加书签
   • 通过左侧导航面板的"Bookmarks"标签查看已保存内容

❓ 常见问题：

• 无法打开Markdown文件？检查文件路径是否正确，支持绝对路径和相对路径
• 中文显示乱码？确保终端支持UTF-8编码，推荐使用Windows Terminal或iTerm2

自定义配置提升使用体验

🔍 本节重点：个性化设置与高级功能启用

通过修改配置文件（frogmouth/data/config.py），可以打造专属使用体验：

1. 界面定制
   调整颜色主题：

   # 修改默认主题为深色模式
   config = {
       "theme": "dark",
       "font_size": 12,
       "line_spacing": 1.2
   }
   

2. 默认行为设置
   配置启动选项：

   # 设置启动时自动打开上次浏览的文件
   config["restore_last_session"] = True
   # 设置默认文件路径
   config["default_path"] = "~/Documents/markdowns/"
   

3. 高级功能启用
   开启实验性特性：

   # 启用目录自动生成
   config["auto_toc"] = True
   # 开启语法高亮
   config["syntax_highlight"] = True
   

❓ 常见问题：

• 修改配置后不生效？需要重启应用使配置生效
• 如何恢复默认设置？删除配置文件后重启应用会自动生成新的默认配置文件