GemReader/README.md

# 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:
   
   ```bash
   git clone <repository-url>
   cd gemreader
   ```

2. Build the application:
   
   ```bash
   go build -o gemreader cmd/gemreader/main.go
   ```

3. Run the application:
   
   ```bash
   ./gemreader <path-to-markdown-file>
   ```

### Building for Windows (.exe)

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

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

For an optimized build with smaller file size:

```bash
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](docs/building.md).

### Go Install

Alternatively, you can install directly using Go:

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

## Usage

Basic usage:

```bash
gemreader <path-to-markdown-file>
```

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

```bash
gemreader
```

Examples:

```bash
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`:

```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

```bash
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:

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

To run tests:

```bash
go test ./...
```

## Contributing

See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to contribute to this project.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Documentation

For more detailed information, check out our documentation:

- [Configuration Guide](docs/configuration.md) - How to configure the application
- [Navigation & Controls](docs/navigation.md) - Detailed keyboard controls and navigation
- [Building Guide](docs/building.md) - Instructions for building the application for different platforms
- [API Documentation](docs/api.md) - Internal API and code structure
- [Architecture](docs/architecture.md) - Project architecture and design patterns
- [Contribution Guide](CONTRIBUTING.md) - How to contribute to the project

## Support

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