richless 0.2.1__tar.gz

richless-0.2.1/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

richless-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DavidJBianco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

richless-0.2.1/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: richless
+Version: 0.2.1
+Summary: LESSOPEN filter for Markdown rendering and syntax highlighting with less
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pygments>=2.0.0
+Requires-Dist: rich>=13.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# richless
+
+A LESSOPEN filter for automatically rendering Markdown files and syntax highlighting source code when using `less`. View your Markdown documents with beautiful formatting and programming language files with syntax highlighting directly in the terminal, without changing how you use `less`.
+
+## Quick Start
+
+```bash
+# 1. Install richless
+git clone <repository-url>
+cd richless
+uv tool install .
+
+# 2. Copy init script and add to your ~/.bashrc or ~/.zshrc
+cp richless-init.sh ~/.richless-init.sh
+echo 'source ~/.richless-init.sh' >> ~/.bashrc  # or ~/.zshrc
+
+# 3. Reload your shell
+source ~/.bashrc  # or ~/.zshrc
+
+# 4. Try it!
+less README.md       # View rendered Markdown
+less richless.py     # View syntax-highlighted Python
+```
+
+## Features
+
+- **Seamless Integration**: Works transparently with `less` via LESSOPEN
+- **Automatic Markdown Rendering**: Recognizes `.md` and `.markdown` files automatically and renders them beautifully
+- **Rich Terminal Formatting**: Beautiful rendering with headers, lists, code blocks, tables, and more
+- **Data Format Highlighting**: Syntax highlighting for JSON, JSONL, YAML, and XML files with automatic detection
+- **Code Highlighting**: Syntax highlighting for 500+ programming languages (Python, JavaScript, Go, Rust, and more)
+- **Works with Wildcards**: `less *.md` or `less *.py` just works
+- **Correct Filenames**: Shows actual filenames in less, not temporary files
+- **Powered by rich and Pygments**: Leverages [rich](https://github.com/Textualize/rich) for beautiful terminal output and [Pygments](https://pygments.org/) for syntax highlighting
+
+## Installation
+
+### Prerequisites
+
+- **Python 3.12+**
+- **[uv](https://github.com/astral-sh/uv)** - Modern Python package manager
+  ```bash
+  # Install uv if you don't have it
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+- **less pager** (standard on macOS and most Linux distributions)
+
+### Step 1: Install richless
+
+Install richless in an isolated virtualenv using uv's tool install feature:
+
+```bash
+# Clone or download this repository
+git clone <repository-url>
+cd richless
+
+# Install richless as a uv tool
+uv tool install .
+
+# Or install directly from git (once published)
+# uv tool install git+https://github.com/yourusername/richless
+```
+
+This installs `richless` and all its dependencies in an isolated virtualenv, making the `richless` command available system-wide without polluting your project environments.
+
+**Note:** If you see a warning about PATH, run:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add this line to your ~/.bashrc or ~/.zshrc to make it permanent
+```
+
+### Step 2: Configure Shell Integration
+
+You have two configuration options depending on your needs:
+
+#### Option 1: Basic LESSOPEN (Minimal setup)
+
+If you prefer not to use the shell wrapper, you can manually set two environment variables. This is a lighter-weight alternative but lacks some features.
+
+**Setup:**
+
+Add these lines to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`:
+
+```bash
+export LESSOPEN="|richless %s"
+export LESS="-R"
+```
+
+Then reload your shell:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+**What you get:**
+- ✅ Automatic Markdown rendering when you run `less file.md`
+- ✅ Syntax highlighting for programming language source files (Python, JavaScript, etc.)
+- ✅ Works with wildcards: `less *.md` or `less *.py`
+- ✅ Fast and lightweight
+
+**Limitations:**
+- ❌ Doesn't work with piped input: `cat file.md | less` won't render
+- ❌ Can't force markdown on non-.md files through `less`
+
+#### Option 2: Transparent Wrapper (Recommended - used by Quick Start)
+
+This is the recommended setup and what Quick Start uses. It provides a smart wrapper around `less` that handles edge cases like piped input and forcing markdown on arbitrary files.
+
+**Setup:**
+
+1. Copy the shell integration script to your home directory:
+   ```bash
+   # From the richless project directory
+   cp richless-init.sh ~/.richless-init.sh
+   ```
+
+2. Source it in your shell configuration:
+   ```bash
+   # Add this line to ~/.bashrc, ~/.zshrc, or ~/.profile
+   source ~/.richless-init.sh
+   ```
+
+3. Reload your shell:
+   ```bash
+   source ~/.bashrc  # or source ~/.zshrc
+   ```
+
+**What you get:**
+- ✅ Everything from Option 1, plus:
+- ✅ Piped input works: `cat file.md | less` renders markdown
+- ✅ Force markdown flag: `less --md document.txt` forces rendering
+- ✅ Auto-detection: Intelligently detects markdown in piped content
+- ✅ Backward compatible: Acts like normal `less` when not needed
+
+**Note:** The shell integration file is compatible with sh, bash, and zsh.
+
+## Usage
+
+Once configured, just use `less` normally! Markdown files will be automatically rendered, and source code files will be syntax highlighted.
+
+### Basic Usage (Both Options)
+
+```bash
+# View a Markdown file (automatically rendered)
+less README.md
+
+# View multiple Markdown files
+less *.md
+
+# View with wildcards
+less docs/**/*.md
+
+# Source code files get syntax highlighting automatically
+less script.py           # Python
+less app.js              # JavaScript
+less main.go             # Go
+less config.json         # JSON
+less styles.css          # CSS
+
+# All standard less options work
+less -N README.md        # Show line numbers
+less -i script.py        # Case-insensitive search
+less +50 README.md       # Start at line 50
+```
+
+### Additional Features (Option 2 / Quick Start)
+
+If you followed the Quick Start or are using Option 2, you also get these features:
+
+```bash
+# Force Markdown rendering on non-.md files
+less --md document.txt
+less -m notes.txt
+
+# Piped input works!
+cat file.md | less
+echo "# Hello\n**World**" | less --md
+
+# Pipe from other commands
+curl https://example.com/README.md | less --md
+grep -A 50 "## Section" doc.md | less
+
+# Auto-detection: if piped content looks like markdown, it renders automatically
+cat file.md | less  # Detects markdown syntax and renders
+```
+
+### Direct richless Usage
+
+You can also call `richless` directly if needed:
+
+```bash
+# Render and pipe to less
+richless document.md | less -R
+
+# Force markdown rendering
+richless --md document.txt | less -R
+
+# Read from stdin
+cat file.md | richless --md - | less -R
+echo "# Test" | richless --md - | less -R
+```
+
+### Standard less Commands
+
+All standard `less` commands work normally inside the pager:
+
+- `/pattern` - Search forward
+- `?pattern` - Search backward
+- `n` / `N` - Next/previous match
+- `g` / `G` - Go to start/end
+- `q` - Quit
+- `h` - Help
+
+## How It Works
+
+**Basic Mode (Option 1):**
+1. When you run `less file.md`, the `LESSOPEN` environment variable tells less to run `richless file.md` first
+2. `richless` detects the `.md` extension and uses the `rich` library to render the Markdown
+3. `rich` renders the Markdown to beautifully formatted ANSI text with proper table support
+4. The formatted output is piped to `less` for viewing
+5. For programming language source files (`.py`, `.js`, `.java`, etc.), `rich` automatically provides syntax highlighting using Pygments
+
+**Transparent Wrapper (Option 2):**
+- The shell function intercepts calls to `less` before they execute
+- For regular files, it passes through to the basic LESSOPEN mechanism
+- For piped input or when `--md` is specified, it saves the content to a temp file and renders it
+- Auto-detection checks piped content for markdown patterns (headers, lists, links, etc.)
+
+## Troubleshooting
+
+### "richless: command not found"
+
+Make sure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add this to your ~/.bashrc or ~/.zshrc
+```
+
+### Piped input doesn't work
+
+If you're using Option 1 (Basic LESSOPEN), piped input won't work. Either:
+- Switch to Option 2 / Quick Start for piped input support
+- Or use: `cat file.md | richless --md - | less -R`
+
+### Colors don't show up
+
+If you're using Option 1 (manual setup), make sure you have the `-R` flag set:
+```bash
+export LESS="-R"
+```
+The init script (Option 2 / Quick Start) sets this automatically.
+
+### Shell function not loading
+
+Make sure you're sourcing the init script, not executing it:
+```bash
+source ~/.richless-init.sh  # Correct
+./richless-init.sh          # Wrong - this won't define the function in your shell
+```
+
+### After sourcing, "less file.md" shows an error
+
+Make sure you've reinstalled richless after any updates:
+```bash
+uv tool uninstall richless
+uv tool install .
+source ~/.richless-init.sh  # Re-source to pick up changes
+```
+
+## Updating
+
+```bash
+# Update to the latest version
+cd /path/to/richless
+git pull  # Get latest changes
+uv tool upgrade richless
+
+# Re-source the init script to pick up any changes
+source ~/.richless-init.sh
+```
+
+## Uninstalling
+
+```bash
+# Remove the tool
+uv tool uninstall richless
+
+# Remove from your shell config (~/.bashrc or ~/.zshrc)
+# Delete or comment out the source line:
+# source ~/.richless-init.sh
+
+# Remove the init script
+rm ~/.richless-init.sh
+
+# If using Option 1 instead, remove these lines:
+# export LESSOPEN="|richless %s"
+# export LESS="-R"
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd richless
+
+# Install dependencies
+uv sync
+
+# Install in development mode
+uv tool install --editable .
+
+# Make changes, then reinstall
+uv tool install --editable . --force
+
+# Test it
+less README.md
+
+# Run tests
+uv run pytest tests/test_richless.py -v
+```
+
+## Dependencies
+
+- [rich](https://github.com/Textualize/rich) - Python library for rich terminal output, Markdown rendering, and syntax highlighting
+- [Pygments](https://pygments.org/) - Syntax highlighting library
+- Python 3.12+
+- uv - Modern Python package manager
+
+## Comparison to Alternatives
+
+**vs. glow / mdcat / bat:**
+- richless integrates directly with `less`, so you use your familiar pager commands
+- Works transparently - no need to remember a different command
+- Supports all standard `less` features (search, navigation, etc.)
+
+**vs. vimpager:**
+- Lighter weight, doesn't require Vim
+- Uses rich library's excellent Markdown rendering with full table support
+- Simple LESSOPEN integration
+
+## License
+
+See LICENSE file for details.

richless-0.2.1/README.md

@@ -0,0 +1,344 @@
+# richless
+
+A LESSOPEN filter for automatically rendering Markdown files and syntax highlighting source code when using `less`. View your Markdown documents with beautiful formatting and programming language files with syntax highlighting directly in the terminal, without changing how you use `less`.
+
+## Quick Start
+
+```bash
+# 1. Install richless
+git clone <repository-url>
+cd richless
+uv tool install .
+
+# 2. Copy init script and add to your ~/.bashrc or ~/.zshrc
+cp richless-init.sh ~/.richless-init.sh
+echo 'source ~/.richless-init.sh' >> ~/.bashrc  # or ~/.zshrc
+
+# 3. Reload your shell
+source ~/.bashrc  # or ~/.zshrc
+
+# 4. Try it!
+less README.md       # View rendered Markdown
+less richless.py     # View syntax-highlighted Python
+```
+
+## Features
+
+- **Seamless Integration**: Works transparently with `less` via LESSOPEN
+- **Automatic Markdown Rendering**: Recognizes `.md` and `.markdown` files automatically and renders them beautifully
+- **Rich Terminal Formatting**: Beautiful rendering with headers, lists, code blocks, tables, and more
+- **Data Format Highlighting**: Syntax highlighting for JSON, JSONL, YAML, and XML files with automatic detection
+- **Code Highlighting**: Syntax highlighting for 500+ programming languages (Python, JavaScript, Go, Rust, and more)
+- **Works with Wildcards**: `less *.md` or `less *.py` just works
+- **Correct Filenames**: Shows actual filenames in less, not temporary files
+- **Powered by rich and Pygments**: Leverages [rich](https://github.com/Textualize/rich) for beautiful terminal output and [Pygments](https://pygments.org/) for syntax highlighting
+
+## Installation
+
+### Prerequisites
+
+- **Python 3.12+**
+- **[uv](https://github.com/astral-sh/uv)** - Modern Python package manager
+  ```bash
+  # Install uv if you don't have it
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+- **less pager** (standard on macOS and most Linux distributions)
+
+### Step 1: Install richless
+
+Install richless in an isolated virtualenv using uv's tool install feature:
+
+```bash
+# Clone or download this repository
+git clone <repository-url>
+cd richless
+
+# Install richless as a uv tool
+uv tool install .
+
+# Or install directly from git (once published)
+# uv tool install git+https://github.com/yourusername/richless
+```
+
+This installs `richless` and all its dependencies in an isolated virtualenv, making the `richless` command available system-wide without polluting your project environments.
+
+**Note:** If you see a warning about PATH, run:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add this line to your ~/.bashrc or ~/.zshrc to make it permanent
+```
+
+### Step 2: Configure Shell Integration
+
+You have two configuration options depending on your needs:
+
+#### Option 1: Basic LESSOPEN (Minimal setup)
+
+If you prefer not to use the shell wrapper, you can manually set two environment variables. This is a lighter-weight alternative but lacks some features.
+
+**Setup:**
+
+Add these lines to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`:
+
+```bash
+export LESSOPEN="|richless %s"
+export LESS="-R"
+```
+
+Then reload your shell:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+**What you get:**
+- ✅ Automatic Markdown rendering when you run `less file.md`
+- ✅ Syntax highlighting for programming language source files (Python, JavaScript, etc.)
+- ✅ Works with wildcards: `less *.md` or `less *.py`
+- ✅ Fast and lightweight
+
+**Limitations:**
+- ❌ Doesn't work with piped input: `cat file.md | less` won't render
+- ❌ Can't force markdown on non-.md files through `less`
+
+#### Option 2: Transparent Wrapper (Recommended - used by Quick Start)
+
+This is the recommended setup and what Quick Start uses. It provides a smart wrapper around `less` that handles edge cases like piped input and forcing markdown on arbitrary files.
+
+**Setup:**
+
+1. Copy the shell integration script to your home directory:
+   ```bash
+   # From the richless project directory
+   cp richless-init.sh ~/.richless-init.sh
+   ```
+
+2. Source it in your shell configuration:
+   ```bash
+   # Add this line to ~/.bashrc, ~/.zshrc, or ~/.profile
+   source ~/.richless-init.sh
+   ```
+
+3. Reload your shell:
+   ```bash
+   source ~/.bashrc  # or source ~/.zshrc
+   ```
+
+**What you get:**
+- ✅ Everything from Option 1, plus:
+- ✅ Piped input works: `cat file.md | less` renders markdown
+- ✅ Force markdown flag: `less --md document.txt` forces rendering
+- ✅ Auto-detection: Intelligently detects markdown in piped content
+- ✅ Backward compatible: Acts like normal `less` when not needed
+
+**Note:** The shell integration file is compatible with sh, bash, and zsh.
+
+## Usage
+
+Once configured, just use `less` normally! Markdown files will be automatically rendered, and source code files will be syntax highlighted.
+
+### Basic Usage (Both Options)
+
+```bash
+# View a Markdown file (automatically rendered)
+less README.md
+
+# View multiple Markdown files
+less *.md
+
+# View with wildcards
+less docs/**/*.md
+
+# Source code files get syntax highlighting automatically
+less script.py           # Python
+less app.js              # JavaScript
+less main.go             # Go
+less config.json         # JSON
+less styles.css          # CSS
+
+# All standard less options work
+less -N README.md        # Show line numbers
+less -i script.py        # Case-insensitive search
+less +50 README.md       # Start at line 50
+```
+
+### Additional Features (Option 2 / Quick Start)
+
+If you followed the Quick Start or are using Option 2, you also get these features:
+
+```bash
+# Force Markdown rendering on non-.md files
+less --md document.txt
+less -m notes.txt
+
+# Piped input works!
+cat file.md | less
+echo "# Hello\n**World**" | less --md
+
+# Pipe from other commands
+curl https://example.com/README.md | less --md
+grep -A 50 "## Section" doc.md | less
+
+# Auto-detection: if piped content looks like markdown, it renders automatically
+cat file.md | less  # Detects markdown syntax and renders
+```
+
+### Direct richless Usage
+
+You can also call `richless` directly if needed:
+
+```bash
+# Render and pipe to less
+richless document.md | less -R
+
+# Force markdown rendering
+richless --md document.txt | less -R
+
+# Read from stdin
+cat file.md | richless --md - | less -R
+echo "# Test" | richless --md - | less -R
+```
+
+### Standard less Commands
+
+All standard `less` commands work normally inside the pager:
+
+- `/pattern` - Search forward
+- `?pattern` - Search backward
+- `n` / `N` - Next/previous match
+- `g` / `G` - Go to start/end
+- `q` - Quit
+- `h` - Help
+
+## How It Works
+
+**Basic Mode (Option 1):**
+1. When you run `less file.md`, the `LESSOPEN` environment variable tells less to run `richless file.md` first
+2. `richless` detects the `.md` extension and uses the `rich` library to render the Markdown
+3. `rich` renders the Markdown to beautifully formatted ANSI text with proper table support
+4. The formatted output is piped to `less` for viewing
+5. For programming language source files (`.py`, `.js`, `.java`, etc.), `rich` automatically provides syntax highlighting using Pygments
+
+**Transparent Wrapper (Option 2):**
+- The shell function intercepts calls to `less` before they execute
+- For regular files, it passes through to the basic LESSOPEN mechanism
+- For piped input or when `--md` is specified, it saves the content to a temp file and renders it
+- Auto-detection checks piped content for markdown patterns (headers, lists, links, etc.)
+
+## Troubleshooting
+
+### "richless: command not found"
+
+Make sure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Add this to your ~/.bashrc or ~/.zshrc
+```
+
+### Piped input doesn't work
+
+If you're using Option 1 (Basic LESSOPEN), piped input won't work. Either:
+- Switch to Option 2 / Quick Start for piped input support
+- Or use: `cat file.md | richless --md - | less -R`
+
+### Colors don't show up
+
+If you're using Option 1 (manual setup), make sure you have the `-R` flag set:
+```bash
+export LESS="-R"
+```
+The init script (Option 2 / Quick Start) sets this automatically.
+
+### Shell function not loading
+
+Make sure you're sourcing the init script, not executing it:
+```bash
+source ~/.richless-init.sh  # Correct
+./richless-init.sh          # Wrong - this won't define the function in your shell
+```
+
+### After sourcing, "less file.md" shows an error
+
+Make sure you've reinstalled richless after any updates:
+```bash
+uv tool uninstall richless
+uv tool install .
+source ~/.richless-init.sh  # Re-source to pick up changes
+```
+
+## Updating
+
+```bash
+# Update to the latest version
+cd /path/to/richless
+git pull  # Get latest changes
+uv tool upgrade richless
+
+# Re-source the init script to pick up any changes
+source ~/.richless-init.sh
+```
+
+## Uninstalling
+
+```bash
+# Remove the tool
+uv tool uninstall richless
+
+# Remove from your shell config (~/.bashrc or ~/.zshrc)
+# Delete or comment out the source line:
+# source ~/.richless-init.sh
+
+# Remove the init script
+rm ~/.richless-init.sh
+
+# If using Option 1 instead, remove these lines:
+# export LESSOPEN="|richless %s"
+# export LESS="-R"
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd richless
+
+# Install dependencies
+uv sync
+
+# Install in development mode
+uv tool install --editable .
+
+# Make changes, then reinstall
+uv tool install --editable . --force
+
+# Test it
+less README.md
+
+# Run tests
+uv run pytest tests/test_richless.py -v
+```
+
+## Dependencies
+
+- [rich](https://github.com/Textualize/rich) - Python library for rich terminal output, Markdown rendering, and syntax highlighting
+- [Pygments](https://pygments.org/) - Syntax highlighting library
+- Python 3.12+
+- uv - Modern Python package manager
+
+## Comparison to Alternatives
+
+**vs. glow / mdcat / bat:**
+- richless integrates directly with `less`, so you use your familiar pager commands
+- Works transparently - no need to remember a different command
+- Supports all standard `less` features (search, navigation, etc.)
+
+**vs. vimpager:**
+- Lighter weight, doesn't require Vim
+- Uses rich library's excellent Markdown rendering with full table support
+- Simple LESSOPEN integration
+
+## License
+
+See LICENSE file for details.

richless-0.2.1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "richless"
+version = "0.2.1"
+description = "LESSOPEN filter for Markdown rendering and syntax highlighting with less"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "rich>=13.8.0",
+    "pygments>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.scripts]
+richless = "richless:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["richless.py", "richless-init.sh", "LICENSE", "README.md"]

richless-0.2.1/richless-init.sh

@@ -0,0 +1,128 @@
+#!/bin/sh
+# richless-init.sh
+#
+# Shell integration for richless - transparent Markdown rendering in less
+#
+# Usage: Add this line to your ~/.bashrc, ~/.zshrc, or ~/.profile:
+#   source /path/to/richless-init.sh
+#
+# This will override the 'less' command to automatically render Markdown files
+# and support additional features like piped input and force-markdown mode.
+#
+# Compatible with: sh, bash, zsh
+
+# Only initialize if richless is available
+if ! command -v richless >/dev/null 2>&1; then
+    echo "Warning: richless command not found. Please install richless first." >&2
+    return 1 2>/dev/null || exit 1
+fi
+
+# Configure LESSOPEN for automatic Markdown detection
+export LESSOPEN="|richless %s"
+export LESS="${LESS:--R}"  # Add -R flag if LESS not already set, otherwise preserve existing
+
+# Transparent wrapper function for less
+# This handles cases where LESSOPEN doesn't work (piped input, force markdown)
+less() {
+    # Check if stdin is a pipe (not a terminal)
+    if [ ! -t 0 ]; then
+        # Reading from pipe - check for --md flag (must be exact match, not substring)
+        local force_markdown=0
+        for arg in "$@"; do
+            case "$arg" in
+                --md|-m) force_markdown=1; break ;;
+            esac
+        done
+
+        # Save piped input to temp file
+        local tmpfile
+        tmpfile=$(mktemp "${TMPDIR:-/tmp}/richless.XXXXXX") || return 1
+        cat > "$tmpfile"
+
+        # Collect non --md/--m arguments for less
+        local clean_args=""
+        for arg in "$@"; do
+            case "$arg" in
+                --md|-m)
+                    # Skip our custom flag
+                    ;;
+                *)
+                    clean_args="${clean_args} ${arg}"
+                    ;;
+            esac
+        done
+
+        # Check if we should render as markdown
+        if [ $force_markdown -eq 1 ]; then
+            richless --md "$tmpfile" | command less -R ${clean_args}
+        else
+            # Check for YAML/JSON first - these should use syntax highlighting, not markdown
+            first_line=$(head -1 "$tmpfile" 2>/dev/null)
+            if printf '%s\n' "$first_line" | grep -qE '^---$|^%YAML|^[[:space:]]*[{[]'; then
+                # Looks like YAML or JSON - use syntax highlighting
+                richless "$tmpfile" | command less -R ${clean_args}
+            # Check for YAML with comments: first non-comment line has key: pattern
+            elif grep -m1 -vE '^[[:space:]]*#|^[[:space:]]*$' "$tmpfile" 2>/dev/null | grep -qE '^[a-zA-Z_][a-zA-Z0-9_-]*:'; then
+                # Looks like YAML with comments - use syntax highlighting
+                richless "$tmpfile" | command less -R ${clean_args}
+            # Auto-detect: check if piped content looks like markdown
+            elif grep -qE '^#{1,6} |^\* |^- |^[0-9]+\. |^\[.*\]\(.*\)|^```|\*\*.*\*\*|^>|^\||^-{3,}|^={3,}' "$tmpfile" 2>/dev/null; then
+                richless --md "$tmpfile" | command less -R ${clean_args}
+            else
+                command less -R ${clean_args} "$tmpfile"
+            fi
+        fi
+
+        # Clean up temp file
+        rm -f "$tmpfile"
+    else
+        # No pipe - check for --md flag among arguments (must be exact match, not substring)
+        local force_markdown=0
+        local has_md_flag=0
+
+        for arg in "$@"; do
+            case "$arg" in
+                --md|-m) has_md_flag=1; break ;;
+            esac
+        done
+
+        if [ $has_md_flag -eq 1 ]; then
+            # Build arrays for files and options
+            local files=""
+            local opts=""
+
+            for arg in "$@"; do
+                case "$arg" in
+                    --md|-m)
+                        force_markdown=1
+                        ;;
+                    -*)
+                        opts="${opts} ${arg}"
+                        ;;
+                    *)
+                        files="${files} ${arg}"
+                        ;;
+                esac
+            done
+
+            # Render each file with markdown
+            for file in ${files}; do
+                if [ -n "$file" ]; then
+                    richless --md "$file" | command less -R ${opts}
+                fi
+            done
+        else
+            # Normal less operation - let LESSOPEN handle it
+            command less "$@"
+        fi
+    fi
+}
+
+# Export the function so it's available in subshells (bash only)
+# Note: zsh doesn't support 'export -f', but functions are automatically available in subshells
+if [ -n "$BASH_VERSION" ]; then
+    export -f less 2>/dev/null || true
+fi
+
+# Suppress any function output
+: # null command to ensure clean sourcing

richless-0.2.1/richless.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+richless - A LESSOPEN filter for Markdown rendering and syntax highlighting.
+
+This utility works as a preprocessor for 'less', automatically rendering
+Markdown files and syntax highlighting code using the rich library.
+"""
+
+import argparse
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.syntax import Syntax
+
+
+def is_markdown_file(filepath: str) -> bool:
+    """Check if the file has a Markdown extension."""
+    ext = Path(filepath).suffix.lower()
+    return ext in ['.md', '.markdown']
+
+
+def detect_syntax_from_content(content: str) -> str:
+    """Detect file type from content when extension is unknown."""
+    if not content:
+        return "text"
+
+    lines = content.split('\n', 20)  # Check first 20 lines
+    first_line = lines[0].strip() if lines else ''
+
+    # YAML detection: starts with --- or %YAML
+    if first_line == '---' or first_line.startswith('%YAML'):
+        return "yaml"
+
+    # JSON detection: starts with { or [
+    if first_line.startswith('{') or first_line.startswith('['):
+        return "json"
+
+    # Shebang detection
+    if first_line.startswith('#!'):
+        if 'python' in first_line:
+            return "python"
+        elif 'bash' in first_line or '/sh' in first_line:
+            return "bash"
+        elif 'node' in first_line:
+            return "javascript"
+        elif 'ruby' in first_line:
+            return "ruby"
+        elif 'perl' in first_line:
+            return "perl"
+
+    # XML/HTML detection
+    if first_line.startswith('<?xml') or first_line.startswith('<!DOCTYPE'):
+        return "xml"
+
+    # YAML detection: look for key: value patterns (possibly after # comments)
+    # Skip comment lines and look for YAML structure
+    for line in lines:
+        stripped = line.strip()
+        # Skip empty lines and comments
+        if not stripped or stripped.startswith('#'):
+            continue
+        # Check for YAML key: value pattern (word followed by colon)
+        if re.match(r'^[a-zA-Z_][a-zA-Z0-9_-]*:\s*', stripped):
+            return "yaml"
+        # If first non-comment line doesn't look like YAML, stop checking
+        break
+
+    return "text"
+
+
+def get_terminal_width() -> int:
+    """Get terminal width, even when stdout is piped."""
+    # Try stderr since stdout is piped through LESSOPEN
+    try:
+        return os.get_terminal_size(sys.stderr.fileno()).columns
+    except (OSError, ValueError):
+        pass
+    # Fall back to shutil (checks COLUMNS env var, then defaults to 80)
+    return shutil.get_terminal_size().columns
+
+
+def render_markdown(content: str) -> None:
+    """Render Markdown content using rich."""
+    width = get_terminal_width()
+    console = Console(force_terminal=True, width=width)
+    md = Markdown(content)
+    console.print(md)
+
+
+def render_syntax(filepath: str, content: str) -> None:
+    """Render code with syntax highlighting using rich."""
+    # Determine lexer from file extension
+    path = Path(filepath)
+    ext = path.suffix.lstrip('.')
+
+    # Map non-standard extensions to their lexer names
+    ext_map = {
+        'jsonl': 'json',  # JSON Lines uses JSON syntax
+    }
+    if ext in ext_map:
+        ext = ext_map[ext]
+
+    # If no recognizable extension, try to detect from content
+    # Temp files from shell wrapper are named richless.XXXXXX (random suffix)
+    if not ext or path.stem == 'richless':
+        ext = detect_syntax_from_content(content)
+
+    # Calculate width needed to avoid truncating long lines
+    # This allows 'less' to handle horizontal scrolling
+    lines = content.splitlines()
+    max_line_length = max((len(line) for line in lines), default=80)
+    width = max(max_line_length + 1, 80)
+
+    # Create console with width to accommodate longest line
+    console = Console(force_terminal=True, width=width)
+
+    # Create Syntax object - use default background to avoid padding
+    syntax = Syntax(content, ext or "text", theme="monokai", line_numbers=False,
+                    background_color="default")
+    console.print(syntax)
+
+
+def main():
+    """Main entry point for richless."""
+    parser = argparse.ArgumentParser(
+        description='LESSOPEN filter for Markdown rendering and syntax highlighting',
+        add_help=True,
+    )
+
+    parser.add_argument('file',
+                       help='File to process (use "-" for stdin)')
+    parser.add_argument('--md', '--markdown',
+                       dest='force_markdown',
+                       action='store_true',
+                       help='Force Markdown rendering even for non-.md files')
+
+    args = parser.parse_args()
+
+    # Strip whitespace from filename (less adds leading space via LESSOPEN)
+    filepath = args.file.strip()
+
+    # Handle stdin input
+    input_file = filepath
+    temp_file = None
+    content = None
+
+    try:
+        if filepath == '-' or filepath == '/dev/stdin':
+            # Read from stdin
+            content = sys.stdin.read()
+            input_file = 'stdin.md' if args.force_markdown else 'stdin.txt'
+        else:
+            # Read from file
+            with open(filepath, 'r', encoding='utf-8') as f:
+                content = f.read()
+            input_file = filepath
+
+        # Determine if we should render as markdown
+        is_markdown = args.force_markdown or is_markdown_file(input_file)
+
+        if is_markdown:
+            render_markdown(content)
+        else:
+            # Syntax highlighting for code files
+            render_syntax(input_file, content)
+
+        return 0
+
+    except FileNotFoundError:
+        print(f"richless: File not found: {args.file}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"richless: Error: {e}", file=sys.stderr)
+        # Fall back to plain output
+        try:
+            if content:
+                print(content, end='')
+            elif filepath not in ['-', '/dev/stdin']:
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    print(f.read(), end='')
+            return 0
+        except Exception:
+            return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())