mdsyntax 0.1.0__tar.gz

mdsyntax-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Run ruff
+        run: ruff check src/
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

mdsyntax-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mdsyntax-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local development
+*.local
+.env

mdsyntax-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-24
+
+### Added
+
+- Initial release
+- Markdown rendering with ANSI formatting
+- Syntax highlighting for code blocks (powered by Pygments)
+- Support for headers, bold, italic, strikethrough, inline code
+- Support for lists (ordered, unordered, task lists)
+- Support for blockquotes and horizontal rules
+- Support for links
+- CLI tool (`mdsyntax`)
+- Auto-detection of 24-bit true color support
+- Configurable code block styling and width

mdsyntax-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to mdsyntax
+
+Thanks for your interest in contributing!
+
+## Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Azaias/mdsyntax.git
+   cd mdsyntax
+   ```
+
+2. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+   ```
+
+3. Install in editable mode with dev dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+This project uses [ruff](https://github.com/astral-sh/ruff) for linting:
+
+```bash
+pip install ruff
+ruff check src/
+ruff format src/
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run tests and linting
+5. Commit with a descriptive message
+6. Push to your fork
+7. Open a Pull Request
+
+## Reporting Issues
+
+Please include:
+- Python version
+- OS and terminal
+- Minimal code to reproduce
+- Expected vs actual behavior

mdsyntax-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Izaiah Meyer
+
+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.

mdsyntax-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mdsyntax
+Version: 0.1.0
+Summary: Render markdown with syntax highlighting in the terminal
+Project-URL: Homepage, https://github.com/Azaias/mdsyntax
+Project-URL: Repository, https://github.com/Azaias/mdsyntax
+Project-URL: Issues, https://github.com/Azaias/mdsyntax/issues
+Author-email: Izaiah Meyer <lolduderlly@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansi,cli,console,markdown,syntax-highlighting,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: pygments>=2.17.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mdsyntax
+
+[![PyPI version](https://img.shields.io/pypi/v/mdsyntax.svg)](https://pypi.org/project/mdsyntax/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mdsyntax.svg)](https://pypi.org/project/mdsyntax/)
+[![CI](https://github.com/Azaias/mdsyntax/actions/workflows/ci.yml/badge.svg)](https://github.com/Azaias/mdsyntax/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Render markdown with syntax highlighting in the terminal.
+
+## Installation
+
+```bash
+pip install mdsyntax
+```
+
+## Usage
+
+### Python API
+
+```python
+from mdsyntax import md_print, md_render
+
+# Print directly to terminal
+md_print("""
+# Hello World
+
+This is **bold** and *italic* text.
+
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+""")
+
+# Get ANSI string for further processing
+output = md_render("Some `inline code` here")
+```
+
+### Command Line
+
+```bash
+# Render a file
+mdsyntax README.md
+
+# Pipe from stdin
+echo "# Hello" | mdsyntax
+
+# Use a different syntax theme
+mdsyntax --style dracula document.md
+
+# List available themes
+mdsyntax --list-styles
+```
+
+## Features
+
+- Headers (h1-h6) with color coding
+- **Bold**, *italic*, ***bold italic***
+- ~~Strikethrough~~
+- `Inline code`
+- Fenced code blocks with syntax highlighting
+- [Links](https://example.com)
+- Unordered and ordered lists
+- Task lists
+- Blockquotes
+- Horizontal rules
+
+## Configuration
+
+### Code Styles
+
+Any [Pygments style](https://pygments.org/styles/) is supported. Popular options:
+
+- `monokai` (default)
+- `dracula`
+- `one-dark`
+- `gruvbox-dark`
+- `nord`
+- `github-dark`
+
+### True Color
+
+By default, md-print auto-detects 24-bit color support via the `COLORTERM` environment variable. You can override this:
+
+```python
+# Force 256-color mode
+md_print(text, true_color=False)
+
+# Force true color
+md_print(text, true_color=True)
+```
+
+## API Reference
+
+### `md_print(text, *, code_style="monokai", code_width=None, true_color=None)`
+
+Print markdown to terminal.
+
+- `text`: Markdown string to render
+- `code_style`: Pygments style name for code blocks
+- `code_width`: Fixed width for code blocks (default: terminal width)
+- `true_color`: Use 24-bit color (default: auto-detect)
+
+### `md_render(...) -> str`
+
+Same arguments as `md_print`, but returns the ANSI-formatted string instead of printing.
+
+### `MarkdownRenderer`
+
+Dataclass for more control:
+
+```python
+from mdsyntax import MarkdownRenderer
+
+renderer = MarkdownRenderer(
+    code_style="dracula",
+    code_width=80,
+    true_color=True,
+)
+output = renderer.render(markdown_text)
+```
+
+### `SyntaxHighlighter`
+
+Standalone code highlighter:
+
+```python
+from mdsyntax import SyntaxHighlighter
+
+hl = SyntaxHighlighter(style="monokai")
+print(hl.highlight("print('hello')", "python"))
+print(SyntaxHighlighter.available_styles())
+```
+
+## License
+
+MIT
+
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

mdsyntax-0.1.0/README.md

@@ -0,0 +1,142 @@
+# mdsyntax
+
+[![PyPI version](https://img.shields.io/pypi/v/mdsyntax.svg)](https://pypi.org/project/mdsyntax/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mdsyntax.svg)](https://pypi.org/project/mdsyntax/)
+[![CI](https://github.com/Azaias/mdsyntax/actions/workflows/ci.yml/badge.svg)](https://github.com/Azaias/mdsyntax/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Render markdown with syntax highlighting in the terminal.
+
+## Installation
+
+```bash
+pip install mdsyntax
+```
+
+## Usage
+
+### Python API
+
+```python
+from mdsyntax import md_print, md_render
+
+# Print directly to terminal
+md_print("""
+# Hello World
+
+This is **bold** and *italic* text.
+
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+""")
+
+# Get ANSI string for further processing
+output = md_render("Some `inline code` here")
+```
+
+### Command Line
+
+```bash
+# Render a file
+mdsyntax README.md
+
+# Pipe from stdin
+echo "# Hello" | mdsyntax
+
+# Use a different syntax theme
+mdsyntax --style dracula document.md
+
+# List available themes
+mdsyntax --list-styles
+```
+
+## Features
+
+- Headers (h1-h6) with color coding
+- **Bold**, *italic*, ***bold italic***
+- ~~Strikethrough~~
+- `Inline code`
+- Fenced code blocks with syntax highlighting
+- [Links](https://example.com)
+- Unordered and ordered lists
+- Task lists
+- Blockquotes
+- Horizontal rules
+
+## Configuration
+
+### Code Styles
+
+Any [Pygments style](https://pygments.org/styles/) is supported. Popular options:
+
+- `monokai` (default)
+- `dracula`
+- `one-dark`
+- `gruvbox-dark`
+- `nord`
+- `github-dark`
+
+### True Color
+
+By default, md-print auto-detects 24-bit color support via the `COLORTERM` environment variable. You can override this:
+
+```python
+# Force 256-color mode
+md_print(text, true_color=False)
+
+# Force true color
+md_print(text, true_color=True)
+```
+
+## API Reference
+
+### `md_print(text, *, code_style="monokai", code_width=None, true_color=None)`
+
+Print markdown to terminal.
+
+- `text`: Markdown string to render
+- `code_style`: Pygments style name for code blocks
+- `code_width`: Fixed width for code blocks (default: terminal width)
+- `true_color`: Use 24-bit color (default: auto-detect)
+
+### `md_render(...) -> str`
+
+Same arguments as `md_print`, but returns the ANSI-formatted string instead of printing.
+
+### `MarkdownRenderer`
+
+Dataclass for more control:
+
+```python
+from mdsyntax import MarkdownRenderer
+
+renderer = MarkdownRenderer(
+    code_style="dracula",
+    code_width=80,
+    true_color=True,
+)
+output = renderer.render(markdown_text)
+```
+
+### `SyntaxHighlighter`
+
+Standalone code highlighter:
+
+```python
+from mdsyntax import SyntaxHighlighter
+
+hl = SyntaxHighlighter(style="monokai")
+print(hl.highlight("print('hello')", "python"))
+print(SyntaxHighlighter.available_styles())
+```
+
+## License
+
+MIT
+
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

mdsyntax-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mdsyntax"
+version = "0.1.0"
+description = "Render markdown with syntax highlighting in the terminal"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Izaiah Meyer", email = "lolduderlly@gmail.com" }
+]
+keywords = [
+    "markdown",
+    "terminal",
+    "console",
+    "syntax-highlighting",
+    "ansi",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+dependencies = [
+    "colorama>=0.4.6",
+    "pygments>=2.17.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/Azaias/mdsyntax"
+Repository = "https://github.com/Azaias/mdsyntax"
+Issues = "https://github.com/Azaias/mdsyntax/issues"
+
+[project.scripts]
+mdsyntax = "mdsyntax.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mdsyntax"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mdsyntax"]

mdsyntax-0.1.0/src/mdsyntax/__init__.py

@@ -0,0 +1,26 @@
+"""
+mdsyntax: Render markdown with syntax highlighting in the terminal.
+
+Usage:
+    >>> from mdsyntax import md_print, md_render
+    >>> md_print("# Hello **world**")
+    >>> output = md_render("Some `code` here")
+"""
+
+from mdsyntax.renderer import (
+    LANG_ALIASES,
+    MarkdownRenderer,
+    SyntaxHighlighter,
+    md_print,
+    md_render,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "md_print",
+    "md_render",
+    "MarkdownRenderer",
+    "SyntaxHighlighter",
+    "LANG_ALIASES",
+    "__version__",
+]

mdsyntax-0.1.0/src/mdsyntax/cli.py

@@ -0,0 +1,82 @@
+"""Command-line interface for md-print."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from mdsyntax import __version__, md_print
+from mdsyntax.renderer import SyntaxHighlighter
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="mdsyntax",
+        description="Render markdown with syntax highlighting in the terminal.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        type=argparse.FileType("r"),
+        default=sys.stdin,
+        help="Markdown file to render (default: stdin)",
+    )
+    parser.add_argument(
+        "-s",
+        "--style",
+        default="monokai",
+        metavar="STYLE",
+        help="Pygments style for code blocks (default: monokai)",
+    )
+    parser.add_argument(
+        "-w",
+        "--width",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Width for code blocks (default: terminal width)",
+    )
+    parser.add_argument(
+        "--no-true-color",
+        action="store_true",
+        help="Disable 24-bit true color (use 256 colors)",
+    )
+    parser.add_argument(
+        "--list-styles",
+        action="store_true",
+        help="List available syntax highlighting styles and exit",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.list_styles:
+        print("Available styles:")
+        for style in sorted(SyntaxHighlighter.available_styles()):
+            print(f"  {style}")
+        return 0
+
+    text = args.file.read()
+    if args.file is not sys.stdin:
+        args.file.close()
+
+    true_color = None if not args.no_true_color else False
+
+    md_print(
+        text,
+        code_style=args.style,
+        code_width=args.width,
+        true_color=true_color,
+    )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mdsyntax-0.1.0/src/mdsyntax/renderer.py

@@ -0,0 +1,368 @@
+"""
+Terminal markdown renderer with syntax highlighting.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from colorama import Back, Fore, Style, init
+from pygments import highlight
+from pygments.formatters import Terminal256Formatter, TerminalTrueColorFormatter
+from pygments.lexers import TextLexer, get_lexer_by_name, guess_lexer
+from pygments.styles import get_all_styles, get_style_by_name
+
+init(autoreset=True)
+
+
+class Ansi:
+    """ANSI escape codes not exposed by colorama."""
+
+    ITALIC = "\033[3m"
+    ITALIC_OFF = "\033[23m"
+    UNDERLINE = "\033[4m"
+    UNDERLINE_OFF = "\033[24m"
+    DIM = "\033[2m"
+    DIM_OFF = "\033[22m"
+    STRIKETHROUGH = "\033[9m"
+    STRIKETHROUGH_OFF = "\033[29m"
+
+
+LANG_ALIASES: dict[str, str] = {
+    "py": "python",
+    "js": "javascript",
+    "ts": "typescript",
+    "sh": "bash",
+    "shell": "bash",
+    "yml": "yaml",
+    "md": "markdown",
+    "c++": "cpp",
+    "c#": "csharp",
+}
+
+
+def _detect_true_color() -> bool:
+    """Check if terminal supports 24-bit color."""
+    colorterm = os.environ.get("COLORTERM", "")
+    return colorterm in ("truecolor", "24bit")
+
+
+def _get_style_bg(style_name: str) -> str:
+    """Extract background color from pygments style as ANSI escape."""
+    try:
+        style = get_style_by_name(style_name)
+        bg = style.background_color
+        if bg and bg.startswith("#") and len(bg) == 7:
+            r, g, b = int(bg[1:3], 16), int(bg[3:5], 16), int(bg[5:7], 16)
+            return f"\033[48;2;{r};{g};{b}m"
+    except Exception:
+        pass
+    return "\033[48;5;236m"  # fallback gray
+
+
+def _visible_len(s: str) -> int:
+    """Length of string excluding ANSI escape sequences."""
+    return len(re.sub(r"\033\[[0-9;]*m", "", s))
+
+
+def _pad_to_width(text: str, width: int) -> str:
+    """Pad string to width, accounting for ANSI codes."""
+    padding = width - _visible_len(text)
+    return text + " " * max(0, padding)
+
+
+class SyntaxHighlighter:
+    """Syntax highlighter using pygments."""
+
+    def __init__(self, style: str = "monokai", true_color: bool | None = None):
+        """
+        Args:
+            style: Pygments style name (monokai, dracula, gruvbox-dark, one-dark, etc.)
+            true_color: Use 24-bit color. None = auto-detect from COLORTERM env var.
+        """
+        if true_color is None:
+            true_color = _detect_true_color()
+
+        formatter_cls = (
+            TerminalTrueColorFormatter if true_color else Terminal256Formatter
+        )
+        self.formatter = formatter_cls(style=style)
+        self.style = style
+
+    def highlight(self, code: str, language: str = "") -> str:
+        """Highlight code and return ANSI-formatted string."""
+        lexer = self._get_lexer(code, language)
+        return highlight(code, lexer, self.formatter).rstrip("\n")
+
+    def _get_lexer(self, code: str, language: str):
+        language = LANG_ALIASES.get(language.lower(), language.lower())
+
+        if language:
+            try:
+                return get_lexer_by_name(language)
+            except Exception:
+                pass
+
+        try:
+            return guess_lexer(code)
+        except Exception:
+            return TextLexer()
+
+    @staticmethod
+    def available_styles() -> list[str]:
+        """Return list of available pygments style names."""
+        return list(get_all_styles())
+
+
+@dataclass
+class MarkdownRenderer:
+    """Renders markdown to ANSI-formatted terminal output."""
+
+    code_style: str = "monokai"
+    code_width: int | None = None  # None = terminal width
+    true_color: bool | None = None  # None = auto-detect
+
+    _highlighter: SyntaxHighlighter = field(init=False, repr=False)
+    _code_bg: str = field(init=False, repr=False)
+
+    def __post_init__(self):
+        self._highlighter = SyntaxHighlighter(
+            style=self.code_style, true_color=self.true_color
+        )
+        self._code_bg = _get_style_bg(self.code_style)
+
+    def render(self, text: str) -> str:
+        """Render markdown text to ANSI-formatted string."""
+        # Normalize line endings
+        text = text.replace("\r\n", "\n").replace("\r", "\n")
+        return "\n".join(self._render_blocks(text))
+
+    def _render_blocks(self, text: str) -> Iterator[str]:
+        """Process block-level elements."""
+        lines = text.split("\n")
+        i = 0
+
+        while i < len(lines):
+            line = lines[i]
+            stripped = line.strip()
+
+            # Code block
+            if stripped.startswith("```"):
+                lang = stripped[3:].strip()
+                code_lines = []
+                i += 1
+
+                while i < len(lines) and not lines[i].strip().startswith("```"):
+                    code_lines.append(lines[i])
+                    i += 1
+
+                yield from self._render_code_block(code_lines, lang)
+                i += 1  # skip closing ```
+                continue
+
+            yield self._render_line(line)
+            i += 1
+
+    def _get_code_width(self) -> int:
+        if self.code_width:
+            return self.code_width
+        return shutil.get_terminal_size().columns
+
+    def _render_code_block(self, code_lines: list[str], language: str) -> Iterator[str]:
+        """Render a fenced code block with syntax highlighting."""
+        width = self._get_code_width()
+        bg = self._code_bg
+        reset = Style.RESET_ALL
+
+        # Header with language label
+        label = f"{language}" if language else ""
+        if label:
+            yield f"{bg}{Fore.LIGHTBLACK_EX}{_pad_to_width(label, width)}{reset}"
+
+        # Highlighted code
+        if code_lines:
+            code = "\n".join(code_lines)
+            highlighted = self._highlighter.highlight(code, language)
+
+            for hl_line in highlighted.split("\n"):
+                yield f"{bg}{_pad_to_width(hl_line, width)}{reset}"
+
+    def _render_line(self, line: str) -> str:
+        """Render a single line of markdown."""
+        stripped = line.strip()
+
+        if not stripped:
+            return ""
+
+        # Horizontal rule
+        if re.match(r"^[-*_]{3,}$", stripped):
+            return f"{Ansi.DIM}{Fore.WHITE}{'─' * 50}{Style.RESET_ALL}"
+
+        # Headers
+        if m := re.match(r"^(#{1,6})\s+(.+)$", stripped):
+            return self._render_header(len(m.group(1)), m.group(2))
+
+        # Blockquotes
+        if stripped.startswith(">"):
+            content = stripped.lstrip(">").strip()
+            rendered = self._render_inline(content)
+            return f"{Fore.MAGENTA}│ {Ansi.ITALIC}{rendered}{Ansi.ITALIC_OFF}{Style.RESET_ALL}"
+
+        # Task lists
+        if m := re.match(r"^[-*]\s+\[([ xX])\]\s+(.+)$", stripped):
+            checked = m.group(1).lower() == "x"
+            marker = f"{Fore.GREEN}✓" if checked else f"{Fore.RED}○"
+            return f"  {marker} {self._render_inline(m.group(2))}{Style.RESET_ALL}"
+
+        # Unordered lists
+        if m := re.match(r"^[-*+]\s+(.+)$", stripped):
+            indent = len(line) - len(line.lstrip())
+            return f"{' ' * indent}{Fore.GREEN}• {Style.RESET_ALL}{self._render_inline(m.group(1))}"
+
+        # Ordered lists
+        if m := re.match(r"^(\d+)\.\s+(.+)$", stripped):
+            indent = len(line) - len(line.lstrip())
+            return f"{' ' * indent}{Fore.GREEN}{m.group(1)}. {Style.RESET_ALL}{self._render_inline(m.group(2))}"
+
+        return self._render_inline(line)
+
+    def _render_header(self, level: int, text: str) -> str:
+        """Render a header with level-appropriate styling."""
+        colors = [
+            Fore.CYAN,
+            Fore.BLUE,
+            Fore.MAGENTA,
+            Fore.GREEN,
+            Fore.YELLOW,
+            Fore.WHITE,
+        ]
+        color = colors[min(level, 6) - 1]
+
+        # Visual prefix for h1-h3
+        prefix = "█" * (4 - level) + " " if level <= 3 else ""
+
+        rendered_text = self._render_inline(text)
+        return f"{color}{Style.BRIGHT}{prefix}{rendered_text}{Style.RESET_ALL}"
+
+    def _render_inline(self, text: str) -> str:
+        """Render inline markdown elements."""
+        # Order matters: process from most specific to least specific
+
+        # Inline code first (protects contents from further processing)
+        code_spans: list[str] = []
+
+        def extract_code(m):
+            code_spans.append(
+                f"{Back.BLACK}{Fore.YELLOW} {m.group(1)} {Style.RESET_ALL}"
+            )
+            return f"\x00CODE{len(code_spans) - 1}\x00"
+
+        text = re.sub(r"`([^`]+)`", extract_code, text)
+
+        # Bold + italic (must come before bold and italic)
+        text = re.sub(
+            r"\*\*\*(.+?)\*\*\*",
+            lambda m: f"{Style.BRIGHT}{Ansi.ITALIC}{m.group(1)}{Ansi.ITALIC_OFF}{Style.NORMAL}",
+            text,
+        )
+
+        # Bold
+        text = re.sub(
+            r"\*\*(.+?)\*\*",
+            lambda m: f"{Style.BRIGHT}{m.group(1)}{Style.NORMAL}",
+            text,
+        )
+        text = re.sub(
+            r"__(.+?)__",
+            lambda m: f"{Style.BRIGHT}{m.group(1)}{Style.NORMAL}",
+            text,
+        )
+
+        # Italic with asterisks (works anywhere)
+        text = re.sub(
+            r"(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)",
+            lambda m: f"{Ansi.ITALIC}{m.group(1)}{Ansi.ITALIC_OFF}",
+            text,
+        )
+
+        # Italic with underscores (only at word boundaries)
+        text = re.sub(
+            r"(?<!\w)_(?!_)(.+?)(?<!_)_(?!\w)",
+            lambda m: f"{Ansi.ITALIC}{m.group(1)}{Ansi.ITALIC_OFF}",
+            text,
+        )
+
+        # Strikethrough
+        text = re.sub(
+            r"~~(.+?)~~",
+            lambda m: f"{Ansi.STRIKETHROUGH}{m.group(1)}{Ansi.STRIKETHROUGH_OFF}",
+            text,
+        )
+
+        # Links
+        text = re.sub(
+            r"\[([^\]]+)\]\(([^)]+)\)",
+            lambda m: f"{Ansi.UNDERLINE}{Fore.BLUE}{m.group(1)}{Ansi.UNDERLINE_OFF}{Style.RESET_ALL}{Ansi.DIM} ({m.group(2)}){Ansi.DIM_OFF}",
+            text,
+        )
+
+        # Restore code spans
+        for i, code in enumerate(code_spans):
+            text = text.replace(f"\x00CODE{i}\x00", code)
+
+        return text
+
+
+def md_print(
+    text: str,
+    *,
+    code_style: str = "monokai",
+    code_width: int | None = None,
+    true_color: bool | None = None,
+) -> None:
+    """
+    Print markdown-formatted text to the terminal.
+
+    Args:
+        text: Markdown text to render.
+        code_style: Pygments style for code blocks.
+        code_width: Width for code blocks (None = terminal width).
+        true_color: Use 24-bit color (None = auto-detect).
+    """
+    renderer = MarkdownRenderer(
+        code_style=code_style,
+        code_width=code_width,
+        true_color=true_color,
+    )
+    print(renderer.render(text))
+
+
+def md_render(
+    text: str,
+    *,
+    code_style: str = "monokai",
+    code_width: int | None = None,
+    true_color: bool | None = None,
+) -> str:
+    """
+    Render markdown text to ANSI-formatted string.
+
+    Args:
+        text: Markdown text to render.
+        code_style: Pygments style for code blocks.
+        code_width: Width for code blocks (None = terminal width).
+        true_color: Use 24-bit color (None = auto-detect).
+
+    Returns:
+        ANSI-formatted string ready for terminal output.
+    """
+    renderer = MarkdownRenderer(
+        code_style=code_style,
+        code_width=code_width,
+        true_color=true_color,
+    )
+    return renderer.render(text)

mdsyntax-0.1.0/tests/test_renderer.py

@@ -0,0 +1,185 @@
+"""Tests for mdsyntax."""
+
+import re
+
+from mdsyntax import LANG_ALIASES, MarkdownRenderer, SyntaxHighlighter, md_render
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text."""
+    return re.sub(r"\033\[[0-9;]*m", "", text)
+
+
+class TestInlineFormatting:
+    def test_bold_asterisks(self):
+        result = md_render("**bold**")
+        assert "bold" in strip_ansi(result)
+        assert "**" not in strip_ansi(result)
+
+    def test_bold_underscores(self):
+        result = md_render("__bold__")
+        assert "bold" in strip_ansi(result)
+        assert "__" not in strip_ansi(result)
+
+    def test_italic_asterisks(self):
+        result = md_render("*italic*")
+        assert "italic" in strip_ansi(result)
+        assert strip_ansi(result).count("*") == 0
+
+    def test_italic_underscores(self):
+        result = md_render("_italic_")
+        assert "italic" in strip_ansi(result)
+
+    def test_underscore_in_word_preserved(self):
+        result = md_render("some_variable_name")
+        assert "some_variable_name" in strip_ansi(result)
+
+    def test_multiple_italics(self):
+        result = md_render("*a* and *b*")
+        plain = strip_ansi(result)
+        assert "a" in plain
+        assert "b" in plain
+        assert "*" not in plain
+
+    def test_bold_italic(self):
+        result = md_render("***both***")
+        assert "both" in strip_ansi(result)
+
+    def test_strikethrough(self):
+        result = md_render("~~deleted~~")
+        assert "deleted" in strip_ansi(result)
+        assert "~~" not in strip_ansi(result)
+
+    def test_inline_code(self):
+        result = md_render("`code`")
+        assert "code" in strip_ansi(result)
+
+    def test_code_protects_formatting(self):
+        result = md_render("`**not bold**`")
+        assert "**not bold**" in strip_ansi(result)
+
+    def test_link(self):
+        result = md_render("[text](https://example.com)")
+        plain = strip_ansi(result)
+        assert "text" in plain
+        assert "example.com" in plain
+
+
+class TestBlockFormatting:
+    def test_header_h1(self):
+        result = md_render("# Title")
+        assert "Title" in strip_ansi(result)
+        assert "#" not in strip_ansi(result)
+
+    def test_header_h2(self):
+        result = md_render("## Subtitle")
+        assert "Subtitle" in strip_ansi(result)
+
+    def test_unordered_list(self):
+        result = md_render("- item")
+        assert "item" in strip_ansi(result)
+        assert "•" in strip_ansi(result)
+
+    def test_ordered_list(self):
+        result = md_render("1. first")
+        assert "first" in strip_ansi(result)
+        assert "1." in strip_ansi(result)
+
+    def test_task_list_checked(self):
+        result = md_render("- [x] done")
+        plain = strip_ansi(result)
+        assert "done" in plain
+        assert "✓" in plain
+
+    def test_task_list_unchecked(self):
+        result = md_render("- [ ] todo")
+        plain = strip_ansi(result)
+        assert "todo" in plain
+        assert "○" in plain
+
+    def test_blockquote(self):
+        result = md_render("> quoted")
+        plain = strip_ansi(result)
+        assert "quoted" in plain
+        assert "│" in plain
+
+    def test_horizontal_rule(self):
+        result = md_render("---")
+        assert "─" in strip_ansi(result)
+
+    def test_code_block(self):
+        result = md_render("```python\nprint('hi')\n```")
+        assert "print" in strip_ansi(result)
+
+
+class TestEdgeCases:
+    def test_empty_string(self):
+        result = md_render("")
+        assert result == ""
+
+    def test_whitespace_only(self):
+        result = md_render("   ")
+        assert strip_ansi(result) == ""
+
+    def test_unclosed_bold(self):
+        result = md_render("**unclosed")
+        assert "**unclosed" in strip_ansi(result)
+
+    def test_unclosed_code_block(self):
+        # Should not crash
+        result = md_render("```python\ncode")
+        assert "code" in strip_ansi(result)
+
+    def test_crlf_normalized(self):
+        result = md_render("line1\r\nline2")
+        assert "\r" not in result
+
+    def test_nested_formatting(self):
+        result = md_render("**bold with `code` inside**")
+        plain = strip_ansi(result)
+        assert "bold with" in plain
+        assert "code" in plain
+
+
+class TestSyntaxHighlighter:
+    def test_highlight_python(self):
+        hl = SyntaxHighlighter()
+        result = hl.highlight("def foo(): pass", "python")
+        assert "def" in strip_ansi(result)
+
+    def test_language_alias(self):
+        hl = SyntaxHighlighter()
+        result = hl.highlight("x = 1", "py")
+        # Should not crash, should highlight
+        assert "x" in strip_ansi(result)
+
+    def test_available_styles(self):
+        styles = SyntaxHighlighter.available_styles()
+        assert "monokai" in styles
+        assert len(styles) > 10
+
+
+class TestMarkdownRenderer:
+    def test_custom_style(self):
+        renderer = MarkdownRenderer(code_style="dracula")
+        result = renderer.render("# Test")
+        assert "Test" in strip_ansi(result)
+
+    def test_custom_width(self):
+        renderer = MarkdownRenderer(code_width=40)
+        result = renderer.render("```\ncode\n```")
+        # Code block lines should be padded to 40 chars
+        lines = result.split("\n")
+        for line in lines:
+            plain = strip_ansi(line)
+            # All code block lines should be exactly 40 chars (padded)
+            if plain:  # non-empty lines
+                assert len(plain) == 40, f"Expected 40, got {len(plain)}: {plain!r}"
+
+
+class TestLangAliases:
+    def test_common_aliases(self):
+        assert LANG_ALIASES["py"] == "python"
+        assert LANG_ALIASES["js"] == "javascript"
+        assert LANG_ALIASES["ts"] == "typescript"
+        assert LANG_ALIASES["sh"] == "bash"