catmd 0.1.0
A CLI markdown viewer that renders markdown files in terminal-friendly format
License: MIT
Requires Python: >=3.10
Keywords: cli, markdown, terminal, viewer

# catmd ⛰︎ 

A CLI MarkDown viewer that renders MarkDown files in terminal-friendly format.

## Features

- **Rich Terminal Rendering**: Beautiful formatted output with colors and styles
- **Complete Markdown Support**: Headers, bold, italic, links, lists, code blocks, blockquotes
- **Line Numbers**: Optional line numbering for easier navigation
- **Color Control**: Toggle colors on/off for different terminal environments
- **Multiple Files**: Process multiple markdown files in sequence
- **Stdin Support**: Read markdown from standard input
- **Fast Performance**: Instant rendering of files up to 1MB

## Installation

### Install with uv (recommended)

```bash
uv add catmd
```


### Install from PyPI

```bash
pip install catmd
```

### Development Installation

```bash
git clone https://github.com/madeonawave/catmd.git
cd catmd
uv sync
```

## Usage

### Basic Usage

```bash
# View a markdown file
catmd README.md

# View multiple files
catmd README.md CHANGELOG.md

# Read from stdin
cat README.md | catmd

# Enable line numbers
catmd --line-numbers README.md

# Disable colors
catmd --no-color README.md
```

### Command Line Options

- `files`: Markdown files to display (optional, reads from stdin if not provided)
- `--no-color`: Disable colors in output
- `--line-numbers`: Show line numbers
- `--help`: Show help message
- `--version`: Show version information

### Examples

```bash
# View a README with all features
catmd --line-numbers README.md

# View multiple files with headers
catmd docs/*.md

# Use in a pipeline
echo "# Hello World\n\nThis is **bold** text." | catmd
```

## Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/madeonawave/catmd.git
cd catmd

# Install in development mode
uv pip install -e .

# Run tests
uv run pytest

# Build package
uv build
```

### Project Structure

```
catmd/
├── src/
│   └── catmd/
│       ├── __init__.py       # Package initialization
│       ├── __main__.py       # Entry point for python -m
│       ├── cli.py            # CLI interface
│       └── renderer.py       # Core functionality
├── tests/                    # Test suite
│   ├── __init__.py
│   └── test_catmd.py
├── docs/                     # Documentation
├── CHANGELOG.md              # Version history
├── LICENSE                  # MIT License
├── README.md               # This file
├── pyproject.toml          # Package configuration
└── .gitignore
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`uv run pytest`)
6. Commit your changes (`git commit -am 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## License

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

## Acknowledgments

- Built with [Rich](https://github.com/Textualize/rich) for terminal rendering
- Inspired by the need for better markdown viewing in terminals
- Thanks to all contributors who have helped make this project better