Upload files to "/"
This commit is contained in:
commit
4587ab01b3
2 changed files with 456 additions and 0 deletions
282
CONTRIBUTING.md
Normal file
282
CONTRIBUTING.md
Normal file
|
|
@ -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!
|
||||||
174
README.md
Normal file
174
README.md
Normal file
|
|
@ -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 <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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue