Skip to content

README.md

Latest commit

 

History

History
340 lines (240 loc) · 8.07 KB

README.md

File metadata and controls

340 lines (240 loc) · 8.07 KB

clickmd

PyPI version Python 3.10+ License: Apache-2.0 Tests codecov

Markdown rendering for CLI applications with syntax highlighting.

clickmd provides beautiful terminal output with:

  • 🎨 Syntax highlighting for code blocks (Python, TypeScript, JSON, YAML, Bash, etc.)
  • 📝 Markdown rendering with headers, bold, links, and more
  • 🔧 Zero dependencies for core functionality
  • 🖱️ Optional Click integration for CLI decorators

Installation

# Core package (no dependencies)
pip install clickmd

# With Click support
pip install clickmd[click]

Quick Start

Basic Usage (No Dependencies)

from clickmd import md, echo

# Render markdown with syntax highlighting
md("""
# Hello World

This is **bold** and this is a [link](https://example.com).

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

""")

Smart echo - auto-detects markdown

echo("## Status Update") echo("Regular text without markdown")


### With Click Integration

```python
import clickmd as click

@click.group()
def cli():
    """My awesome CLI tool"""
    pass

@cli.command()
@click.option("--name", "-n", default="World")
def hello(name: str):
    """Say hello"""
    click.md(f"""
## 👋 Hello, {name}!

Welcome to **clickmd** - making CLIs beautiful.
    """)

if __name__ == "__main__":
    cli()

Features

Syntax Highlighting

clickmd provides syntax highlighting for multiple languages:

Language Extensions Highlight Features
Python .py Keywords, strings, comments, decorators
TypeScript/JavaScript .ts, .js Keywords, strings, template literals
JSON .json Keys, strings, numbers, booleans
YAML .yaml, .yml Keys, values, comments
Bash/Shell .sh, .bash Commands, comments
Markdown .md Headers, bold, links
Log .log Errors (red), warnings (yellow), success (green)

Markdown Elements

from clickmd import md

md("""
# Heading 1
## Heading 2
### Heading 3

**Bold text** and regular text.

[Links](https://example.com) are supported.

```python
# Code blocks with syntax highlighting
print("Hello, World!")
  • List items
  • Are rendered
  • Correctly """)

### MarkdownRenderer Class

For more control, use the `MarkdownRenderer` class directly:

```python
from clickmd import MarkdownRenderer
import sys

renderer = MarkdownRenderer(use_colors=True, stream=sys.stdout)
renderer.heading(1, "My Title")
renderer.codeblock("python", 'print("Hello!")')

Progress and Status Output

from clickmd import md

# Log-style output with automatic coloring
md("""
```log
🚀 Starting process...
📦 Installing dependencies...
✅ Build successful!
⚠️ Warning: deprecated API
🛑 Error: connection failed

""")


## API Reference

### Core Functions

#### `md(text: str) -> None`
Render markdown text with syntax highlighting.

#### `echo(message, file=None, nl=True, err=False, color=None) -> None`
Smart echo that auto-detects markdown and renders it.

#### `render_markdown(text, text_lang="markdown", stream=None, use_colors=True) -> None`
Low-level markdown rendering function.

#### `get_renderer(stream=None, use_colors=True) -> MarkdownRenderer`
Get a `MarkdownRenderer` instance.

### Click Decorators (requires `click` package)

When `click` is installed, these decorators are available:

- `@clickmd.group()` - Create a command group
- `@clickmd.command()` - Create a command
- `@clickmd.option()` - Add an option
- `@clickmd.argument()` - Add an argument
- `@clickmd.pass_context` - Pass Click context
- `clickmd.Choice` - Choice type
- `clickmd.Path` - Path type

### Constants

- `CLICK_AVAILABLE: bool` - Whether Click is installed

## Additional Features

### Interactive Menus

```python
import clickmd

choice = clickmd.menu("## Choose Provider", [
    ("groq", "Groq — fast & free tier"),
    ("openrouter", "OpenRouter — multi-model"),
    ("ollama", "Ollama — local, no API key"),
])

Tables & Panels

from clickmd import table, panel

table(
    headers=["Name", "Version", "Status"],
    rows=[
        ["clickmd", "1.1.0", "✅ OK"],
        ["click", "8.1.7", "✅ OK"],
    ],
)

panel("Deployment complete!", title="Success", style="green")

Logger

from clickmd import get_logger

log = get_logger("myapp")
log.info("Starting process...")
log.success("Build complete!")
log.warning("Deprecated API")
log.error("Connection failed")

Themes

from clickmd import set_theme, list_themes

list_themes()            # Show available themes
set_theme("monokai")     # Switch theme

Developer Tools

from clickmd import debug, inspect_obj, diff, tree

debug(my_variable)                    # Pretty-print with type info
inspect_obj(my_object)                # Show object attributes
diff("old text", "new text")          # Side-by-side diff
tree("/path/to/dir")                  # Directory tree

Examples

See the examples/ directory for 17 demo scripts:

  • basic.py — Basic markdown rendering
  • cli_app.py — Full CLI application with Click
  • custom_renderer.py — Custom renderer configuration
  • colored_logging.py — Log-style colored output
  • phase1_features.py — Tables, panels, blockquotes, checklists
  • phase3_progress.py — Progress bars, spinners, live updates
  • phase4_themes.py — Theming system
  • phase5_devtools.py — Debug, inspect, diff, tree tools
  • logger_usage.py — Structured logging
  • markdown_help.py — Markdown help formatter for Click

Project Structure

clickmd/
├── src/clickmd/          # Package source (src layout)
│   ├── __init__.py       # Public API: md(), echo(), menu(), select()
│   ├── renderer.py       # Core markdown renderer & syntax highlighting
│   ├── decorators.py     # Click decorator re-exports
│   ├── help.py           # Markdown help formatter for Click
│   ├── logger.py         # Markdown-aware structured logger
│   ├── progress.py       # Progress bars, spinners, live updates
│   ├── themes.py         # Color themes & NO_COLOR support
│   ├── devtools.py       # Debug, inspect, diff, tree tools
│   ├── rich_backend.py   # Optional Rich integration
│   └── py.typed          # PEP 561 type marker
├── tests/                # Test suite (69 tests)
├── examples/             # 17 demo scripts
├── docs/                 # API reference & contributing guide
├── scripts/              # Build & version tools
├── tools/                # Markdown-to-HTML converter
├── pyproject.toml        # Project config (hatchling)
└── Makefile              # Dev commands

Development

# Clone the repository
git clone https://github.com/wronai/clickmd.git
cd clickmd

# Install development dependencies
pip install -e ".[dev,click]"

# Run tests
make test

# Run linter & format
make lint
make format

# Build & publish
make build
make publish

License

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Licensed under Apache-2.0.

Apache License 2.0 - see LICENSE for details.

Author

Tom Sapletta

Tom Sapletta

Tom Sapletta

Tom Sapletta

Created by Tom Sapletta - tom@sapletta.com

Contributing

Contributions are welcome! Please read our Contributing Guide first.

Related Projects

  • Click - Python CLI framework
  • Rich - Rich text and beautiful formatting