frogmouth

repository·main·Indexed 25 days ago

A terminal-based Markdown document viewer and browser built with the Textual framework. It supports browsing local Markdown files and remote GitHub repositories, featuring a navigation stack, history, bookmarks, a table of contents, and light/dark mode themes. Compatible with Linux, macOS, and Windows using Python 3.8+.

Tokens: 1.1K
Snippets: 1
Records: 13
Agent score: 84%

What's inside frogmouth

Run Frogmouth
main
To start the application, run the frogmouth command. You can optionally provide a path to a local Markdown file to open it immediately. Navigation is supported via both mouse and keyboard (use <kbd>tab</kbd> and <kbd>shift</kbd>+<kbd>tab</kbd>` to cycle through controls).
https://github.com/textualize/frogmouth/blob/main/README.md
Install Frogmouth
main
You can install Frogmouth using pipx, pip, or Homebrew. After installation, the frogmouth command should be available in your system path.
https://github.com/textualize/frogmouth/blob/main/README.md
Load Markdown files from GitHub
main
Frogmouth allows you to load README files directly from GitHub repositories using the gh command syntax. This can be used via the CLI or typed directly into the app's address bar.
```
frogmouth gh textualize/textual
```
https://github.com/textualize/frogmouth/blob/main/README.md
Frogmouth Compatibility and Requirements
main
Frogmouth is compatible with Linux, macOS, and Windows. It requires Python 3.8 or higher.
https://github.com/textualize/frogmouth/blob/main/README.md
Use the Main screen to visit locations
main
The Main screen class provides a visit method to navigate to different resources. It intelligently handles different types of input:
- Markdown files/URLs: If the location is identified as Markdown (via maybe_markdown), it is loaded into the Viewer widget.
- Existing local Paths: If the location is a Path that exists but is not Markdown, the application attempts to open it using the operating system's default handler.
- Non-existent local Paths: If a Path is provided but does not exist, an ErrorDialog is displayed.
- Other URLs: If the location is a URL that does not appear to be Markdown, the application hands it off to the operating system to open in a web browser.
https://github.com/textualize/frogmouth/blob/main/frogmouth/screens/main.py
Manage application theme
main
The action_toggle_theme method toggles between light and dark modes. It updates the application configuration (persisted via save_config) and immediately updates the app.dark property to reflect the change in the UI.
https://github.com/textualize/frogmouth/blob/main/frogmouth/screens/main.py
Add a bookmark for the current location
main
You can programmatically add a bookmark for the currently viewed file using action_bookmark_this(). This method triggers an InputDialog to allow the user to specify a title for the bookmark. The bookmark is then added to the Navigation pane's bookmarks collection.
https://github.com/textualize/frogmouth/blob/main/frogmouth/screens/main.py
Run the Frogmouth application with run()
main
The run() function is the simplest entry point to start the application. It internally calls get_args() to parse command-line input and then initializes and runs the MarkdownViewer.
https://github.com/textualize/frogmouth/blob/main/frogmouth/app/app.py
Get parsed command line arguments with get_args()
main
The get_args() function uses argparse to parse command-line input. It returns a Namespace object containing the file list and handles the --version flag.
https://github.com/textualize/frogmouth/blob/main/frogmouth/app/app.py

Main screen keyboard bindings

main

The Main screen uses the following keyboard bindings for navigation and application control:

Key	Action	Description
`/ , :`	`omnibox`	Open the Omnibox (hidden by default)
`ctrl+b`	`bookmarks`	Open Bookmarks pane
`ctrl+d`	`bookmark_this`	Bookmark the current location
`ctrl+l`	`local_files`	Open Local Files pane
`ctrl+left`	`backward`	Go backward in history
`ctrl+right`	`forward`	Go forward in history
`ctrl+r`	`reload`	Reload the current document
`ctrl+t`	`table_of_contents`	Show Table of Contents
`ctrl+y`	`history`	Open History pane
`escape`	`escape`	Exit app or clear/focus Omnibox
`f1`	`help`	Show Help dialog
`f2`	`about`	Show About dialog
`ctrl+n`	`navigation`	Toggle Navigation sidebar
`ctrl+q`	`app.quit`	Quit the application
`f10`	`toggle_theme`	Toggle light/dark mode

Run Frogmouth via the CLI
main
Frogmouth is a Markdown viewer for the terminal. You can run it by passing the path to a Markdown file as a positional argument. If no file is provided, the application starts without a specific file loaded.
Arguments:
- file: The Markdown file(s) to view. Supports multiple files via nargs="*".
Flags:
- -v, --version: Show version information (including the version of the underlying textual library).
https://github.com/textualize/frogmouth/blob/main/frogmouth/app/app.py
Run the Frogmouth application via CLI
main
You can launch the Frogmouth application directly from the command line using the frogmouth command (if installed as a package) or by running the module with Python. This invokes the application's main entry point.
https://github.com/textualize/frogmouth/blob/main/frogmouth/__main__.py