GemReader

A terminal-based markdown viewer designed for reading documentation and notes directly in your terminal. GemReader provides an intuitive interface with navigation and table of contents functionality.

Features

• Terminal-based viewing: Display markdown files directly in your terminal
• Intuitive navigation: Navigate documents using keyboard shortcuts
• Table of contents: Automatic generation and navigation of document headers
• Configurable: Customize the application with a simple config.toml file
• Responsive interface: Adapts to different terminal sizes

Installation

Prerequisites

• Go 1.24 or higher

Build from Source

1. Clone the repository:

   git clone <repository-url>
   cd gemreader
   

2. Build the application:

   go build -o gemreader cmd/gemreader/main.go
   

3. Run the application:

   ./gemreader <path-to-markdown-file>
   

Building for Windows (.exe)

To create a Windows executable (.exe), use the following command:

go build -o gemreader.exe cmd/gemreader/main.go

For an optimized build with smaller file size:

go build -ldflags "-s -w" -o gemreader.exe cmd/gemreader/main.go

For more detailed build instructions, including cross-compilation and advanced options, see the Building Guide.

Go Install

Alternatively, you can install directly using Go:

go install gemreader@latest
gemreader <path-to-markdown-file>

Usage

Basic usage:

gemreader <path-to-markdown-file>

You can also run GemReader without arguments if you have a default file configured:

gemreader

Examples:

gemreader sample.md
gemreader  # Uses default_file from config.toml

Configuration

GemReader uses a config.toml file for configuration. The configuration file should be placed in the same directory where you run the application.

Example config.toml:

title = "GemReader"
default_file = "sample.md"

Keyboard Controls

Key	Action
↑ / k	Move up one line
↓ / j	Move down one line
PgUp / Ctrl+U	Move up one page
PgDn / Ctrl+D	Move down one page
g / Home	Go to top of document
G / End	Go to end of document
Tab	Switch between TOC and content panes
h / ?	Toggle help visibility
q / Ctrl+C	Quit the application
Enter	Jump to selected TOC entry (when in TOC pane)

Table of Contents Navigation

When in TOC mode:

• Use ↑ / ↓ keys to navigate between headings
• Press Enter to jump to the selected heading
• Use Tab to switch between TOC and content panes

Project Structure

gemreader/
├── cmd/
│   └── gemreader/
│       └── main.go         # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go       # Configuration loading
│   └── tui/
│       └── tui.go          # Terminal user interface
├── config.toml             # Default configuration
├── sample.md               # Sample markdown file
├── go.mod                  # Go module file
├── go.sum                  # Go module checksums
└── README.md               # This file

Development

To run in development mode:

go run cmd/gemreader/main.go <path-to-markdown-file>

To run tests:

go test ./...

Contributing

See the CONTRIBUTING.md file for details on how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

For more detailed information, check out our documentation:

• Configuration Guide - How to configure the application
• Navigation & Controls - Detailed keyboard controls and navigation
• Building Guide - Instructions for building the application for different platforms
• API Documentation - Internal API and code structure
• Architecture - Project architecture and design patterns
• Contribution Guide - How to contribute to the project

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.