From 4587ab01b3f403687d6ea6dd337f16c3e908233f Mon Sep 17 00:00:00 2001 From: Moto Date: Mon, 29 Sep 2025 22:40:36 -0500 Subject: [PATCH] Upload files to "/" --- CONTRIBUTING.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 174 ++++++++++++++++++++++++++++++ 2 files changed, 456 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7a9c3ff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,282 @@ +# Contributing to GemReader + +Thank you for your interest in contributing to GemReader! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +1. [Code of Conduct](#code-of-conduct) +2. [Development Setup](#development-setup) +3. [Project Structure](#project-structure) +4. [Coding Standards](#coding-standards) +5. [Testing](#testing) +6. [Pull Request Process](#pull-request-process) +7. [Development Workflow](#development-workflow) +8. [Reporting Issues](#reporting-issues) + +## Code of Conduct + +By participating in this project, you agree to abide by the following code of conduct: + +- Be respectful and considerate to others +- Provide constructive feedback +- Welcome different viewpoints and experiences +- Focus on what is best for the community +- Show empathy towards other community members + +## Development Setup + +### Prerequisites + +- Go 1.24 or higher +- Git +- A terminal that supports ANSI escape sequences + +### Getting Started + +1. Fork the repository on GitHub +2. Clone your fork: + + ```bash + git clone https://github.com/YOUR-USERNAME/gemreader.git + cd gemreader + ``` + +3. Create a new branch for your changes: + + ```bash + git checkout -b feature/your-feature-name + ``` + +4. Install dependencies: + + ```bash + go mod tidy + ``` + +5. Run the application in development mode: + + ```bash + go run cmd/gemreader/main.go sample.md + ``` + +### Development Environment + +For the best development experience, we recommend: + +- Using a Go-aware IDE such as VS Code with Go extension, GoLand, or Vim with Go plugins +- Terminal that supports color and special characters for proper TUI rendering +- Using `go fmt` to format your code before committing + +## Project Structure + +``` +gemreader/ +├── cmd/ +│ └── gemreader/ +│ └── main.go # Application entry point +├── internal/ +│ ├── config/ +│ │ └── config.go # Configuration loading +│ └── tui/ +│ └── tui.go # Terminal user interface +├── docs/ # Documentation files +├── config.toml # Default configuration +├── sample.md # Sample markdown file +├── go.mod # Go module file +├── go.sum # Go module checksums +├── README.md # Main documentation file +└── CONTRIBUTING.md # This file +``` + +## Coding Standards + +### Go Code Standards + +- Follow the official [Go formatting conventions](https://golang.org/doc/effective_go.html) +- Use `go fmt` to format your code before committing +- Write clear, descriptive names for variables, functions, and types +- Include comments for exported functions and types +- Write idiomatic Go code following the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) + +### Naming Conventions + +- Use camelCase for variable and function names +- Use PascalCase for exported functions and types +- Use descriptive names that clearly indicate purpose +- Keep function names concise but meaningful + +### Comments and Documentation + +- Document exported functions and types with clear explanations +- Use complete sentences with proper capitalization and punctuation +- Include examples when helpful +- Comment complex logic to explain the "why" not just the "what" + +## Testing + +### Running Tests + +Run all tests in the project: + +```bash +go test ./... +``` + +Run tests with verbose output: + +```bash +go test -v ./... +``` + +Run tests and show coverage: + +```bash +go test -cover ./... +``` + +### Writing Tests + +- Write tests for new functionality +- Ensure tests cover edge cases +- Use descriptive test names in the format `TestFunctionName_Scenario_ExpectedBehavior` +- Follow the table-driven test pattern when appropriate + +### Test Structure + +Tests should follow this pattern: + +- Setup test data and inputs +- Execute the function under test +- Assert the results match expected outcomes +- Clean up if necessary + +## Pull Request Process + +### Before Submitting + +1. Ensure your code follows the coding standards +2. Add tests for new functionality +3. Update documentation as needed +4. Run all tests to ensure they pass +5. Format your code with `go fmt` +6. Run linters to check for issues (e.g., `go vet ./...`) + +### Creating a Pull Request + +1. Ensure your branch is up to date with the main branch: + + ```bash + git fetch origin + git rebase origin/main + ``` + +2. Push your changes to your fork: + + ```bash + git push origin feature/your-feature-name + ``` + +3. Create a pull request on GitHub +4. Fill out the pull request template (if available) +5. Provide a clear description of your changes +6. Link to any related issues + +### Pull Request Review + +- Allow time for others to review your code +- Be responsive to feedback and make requested changes +- Maintain a positive attitude during discussions +- Ensure all CI checks pass before merging + +## Development Workflow + +### New Features + +1. Create an issue describing the feature (if not already created) +2. Fork and create a branch from the main branch +3. Implement the feature +4. Write tests for the new functionality +5. Update documentation as needed +6. Submit a pull request following the process above + +### Bug Fixes + +1. Create an issue describing the bug (if not already created) +2. Fork and create a branch from the main branch +3. Write a test that reproduces the bug +4. Implement the fix +5. Ensure the test passes +6. Submit a pull request following the process above + +### Refactoring + +1. Ensure all tests pass before starting +2. Make small, incremental changes +3. Run tests frequently to ensure nothing is broken +4. Submit changes as a pull request with clear description + +## Reporting Issues + +### Before Creating an Issue + +- Check the [existing issues](https://github.com/your-repo/gemreader/issues) to avoid duplicates +- Ensure you're using the latest version of the application +- Try to reproduce the issue on different systems if possible + +### Creating an Issue + +When creating an issue, please include: + +- Clear title and description +- Steps to reproduce the issue +- Expected behavior +- Actual behavior +- Environment information (Go version, OS, terminal) +- Any relevant screenshots or error messages + +### Good Issues + +- Include detailed steps to reproduce +- Provide expected vs. actual behavior +- Include environment information +- Are specific rather than broad +- Include examples when helpful + +## Development Tools + +### Recommended Setup + +The following tools will help with development: + +- **Editor**: VS Code with Go extension, GoLand, or Vim with Go plugins +- **Terminal**: A modern terminal that supports ANSI escape sequences (Windows Terminal, iTerm2, etc.) +- **Git**: Properly configured with your GitHub account + +### Development Commands + +Useful commands during development: + +- `go run cmd/gemreader/main.go sample.md`: Run the application +- `go build -o gemreader cmd/gemreader/main.go`: Build the application +- `go build -o gemreader.exe cmd/gemreader/main.go`: Build Windows executable +- `go build -ldflags "-s -w" -o gemreader.exe cmd/gemreader/main.go`: Build optimized Windows executable +- `go test ./...`: Run all tests +- `go fmt ./...`: Format all Go files +- `go vet ./...`: Check for potential issues +- `go mod tidy`: Update dependencies + +For detailed build instructions including cross-platform compilation and optimization options, see the [Building Guide](docs/building.md). + +## Getting Help + +If you need help with the development process: + +- Open an issue with your question +- Check the documentation in the `docs/` directory +- Review existing code to see how similar features are implemented + +## Recognition + +All contributions are valuable to the project. Contributors will be recognized in the project documentation and release notes. + +Thank you again for your interest in contributing to GemReader! diff --git a/README.md b/README.md new file mode 100644 index 0000000..3fae290 --- /dev/null +++ b/README.md @@ -0,0 +1,174 @@ +# 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 + cd gemreader + ``` + +2. Build the application: + + ```bash + go build -o gemreader cmd/gemreader/main.go + ``` + +3. Run the application: + + ```bash + ./gemreader + ``` + +### 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 +``` + +## Usage + +Basic usage: + +```bash +gemreader +``` + +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 +``` + +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.