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