174 lines
4.7 KiB
Markdown
174 lines
4.7 KiB
Markdown
# 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.
|