txmd 0.4.0

A textual markdown viewer CLI

A modern, feature-rich terminal-based Markdown viewer with pipeline support, built with Textual.

Table of Contents

• Features
• Installation
• Usage
  • Basic Usage
  • Pipeline Usage
  • Navigation
  • Keybindings Reference
• Examples
• Supported Markdown Features
• Documentation
• Development
• Contributing
• Troubleshooting
• Roadmap
• License

Features

• 📝 Render Markdown files directly in your terminal
• 🔄 Pipeline support - pipe markdown content directly to txmd
• 🗂️ Dynamic Table of Contents - Navigate long documents with hierarchical TOC
• 🎨 Syntax highlighting for code blocks
• 📊 Table support
• 🖼️ Beautiful TUI interface powered by Textual
• ⌨️ Vim-style navigation (j/k for scrolling)
• 🚀 Fast and lightweight

Installation

You can install txmd using pip:

pip install txmd

Or using Poetry:

poetry add txmd

Usage

Basic Usage

View a Markdown file:

txmd README.md

Pipeline Usage

Pipe content to txmd:

echo "# Hello World" | txmd
cat document.md | txmd
curl https://raw.githubusercontent.com/user/repo/main/README.md | txmd

Table of Contents

For documents with headers, txmd provides a dynamic Table of Contents sidebar:

Toggle TOC:

• t - Show/hide the Table of Contents panel

Using the TOC:

• The TOC automatically parses all headers (# through ######) in your document
• Headers are displayed in a hierarchical tree structure
• Navigate with arrow keys (↑/↓) when TOC is focused
• Press Enter to expand/collapse sections with subsections
• Press Space to jump to the selected section (positions it at top of screen)
• Click a header to jump directly to that section
• Leaf sections (no subsections) have no expand icon for cleaner display
• Hidden by default to maximize reading space

The TOC is especially useful for:

• Long documentation files with many sections
• README files with multiple chapters
• Technical documentation with nested topics
• Any structured markdown content

Navigation

Inside the viewer, you can navigate using vim-style keys or traditional navigation keys:

Basic Scrolling:

• j or ↓ - Scroll down one line
• k or ↑ - Scroll up one line

Page Scrolling:

• Space or Page Down - Scroll down one page
• b or Page Up - Scroll up one page

Jump to Position:

• Home - Jump to the top of the document
• End - Jump to the bottom of the document

Exit:

• q or Ctrl+C - Quit the viewer

Keybindings Reference

Complete list of all keybindings:

Key(s)	Action	Description
j, ↓	Scroll Down	Move down one line
k, ↑	Scroll Up	Move up one line
Space, Page Down	Page Down	Scroll down by viewport height
b, Page Up	Page Up	Scroll up by viewport height
Home	Jump to Top	Scroll to the beginning of the document
End	Jump to Bottom	Scroll to the end of the document
t	Toggle TOC	Show/hide Table of Contents sidebar
q, Ctrl+C	Quit	Exit the application

Note: All scrolling operations happen instantly without animation for a responsive feel.

Examples

txmd includes a collection of example markdown files demonstrating various features:

# View basic markdown features
txmd examples/basic.md

# See syntax highlighting for various languages
txmd examples/code-blocks.md

# Explore table formatting
txmd examples/tables.md

# Check out advanced features
txmd examples/advanced.md

See the examples directory for more information and sample files.

Supported Markdown Features

txmd supports all standard Markdown elements through Textual's Markdown widget:

Feature	Support	Notes
Headers	✅ Full	All levels (H1-H6)
Text Formatting	✅ Full	Bold, italic, strikethrough
Lists	✅ Full	Ordered, unordered, nested
Code Blocks	✅ Full	Syntax highlighting for 100+ languages
Inline Code	✅ Full	Monospace formatting
Tables	✅ Full	With column alignment
Blockquotes	✅ Full	Including nested quotes
Horizontal Rules	✅ Full	Visual separators
Links	✅ Full	Displayed with formatting
Images	⚠️ Partial	Text representation in terminal

Code Syntax Highlighting

Syntax highlighting is supported for many languages including:

• Python, JavaScript, TypeScript, Rust, Go
• Java, C, C++, C#, Ruby, PHP
• Bash, Shell, PowerShell
• HTML, CSS, SCSS, JSON, YAML, TOML, XML
• SQL, Markdown, and many more

Pipeline Integration

txmd is designed to work seamlessly in Unix pipelines. This means you can:

# Preview markdown before committing
git show HEAD:README.md | txmd

# View remote markdown files
curl -s https://raw.githubusercontent.com/user/repo/main/README.md | txmd

# View markdown from any command output
echo "# Dynamic Content\n\nGenerated at $(date)" | txmd

# Process and view markdown
grep -A 10 "## Section" document.md | txmd

How it works: txmd detects piped input, reads the content, and then restores terminal control by reopening /dev/tty. This allows the TUI to function normally even when receiving piped input.

Platform Note: Full pipeline support works on Linux and macOS. On Windows, use WSL or Windows Terminal for best results.

Documentation

Comprehensive documentation is available:

• CONTRIBUTING.md - Detailed contribution guidelines, development setup, coding standards, and PR process
• ARCHITECTURE.md - Technical architecture, design decisions, and component details
• TROUBLESHOOTING.md - Solutions for common issues and debugging help
• CLAUDE.md - AI assistant context and project overview
• examples/ - Sample markdown files demonstrating features

Development

Quick Start

1. Clone the repository:

   git clone https://github.com/guglielmo/txmd
   cd txmd
   

2. Install Poetry (if not already installed):

   curl -sSL https://install.python-poetry.org | python3 -
   

3. Install dependencies:

   poetry install
   

4. Run from source:

   poetry run txmd README.md
   

5. Run tests:

   poetry run pytest
   

Code Quality

# Format code
poetry run black txmd/

# Sort imports
poetry run isort txmd/

# Lint code
poetry run flake8 txmd/

# Run all checks
poetry run black txmd/ && poetry run isort txmd/ && poetry run flake8 txmd/ && poetry run pytest

Project Structure

txmd/
├── txmd/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # Main application (CLI + TUI)
│   └── toc.py           # Table of Contents module
├── tests/
│   ├── __init__.py
│   ├── test_cli.py      # CLI test suite
│   └── test_toc.py      # TOC test suite
├── examples/            # Example markdown files
│   ├── basic.md
│   ├── code-blocks.md
│   ├── tables.md
│   ├── advanced.md
│   └── README.md
├── CONTRIBUTING.md      # Contribution guidelines
├── ARCHITECTURE.md      # Technical documentation
├── TROUBLESHOOTING.md   # Common issues and solutions
├── CLAUDE.md            # AI assistant context
├── pyproject.toml       # Poetry configuration
└── README.md            # This file

For detailed development information, see CONTRIBUTING.md and ARCHITECTURE.md.

Contributing

Contributions are welcome and appreciated! We'd love your help making txmd better.

Quick Contribution Guide

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run quality checks:

   poetry run black txmd/
   poetry run isort txmd/
   poetry run flake8 txmd/
   poetry run pytest
   

5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Open a Pull Request

What to Contribute

• 🐛 Bug fixes - Help us squash bugs
• ✨ New features - Add capabilities from the roadmap
• 📝 Documentation - Improve or add documentation
• ✅ Tests - Increase test coverage
• 🎨 Examples - Create new example markdown files

Before Contributing

Please read our comprehensive CONTRIBUTING.md guide which covers:

• Development setup and workflow
• Coding standards and style guide
• Testing guidelines
• PR process and review guidelines
• Project architecture and structure

Getting Help

• Check existing issues
• Read the TROUBLESHOOTING.md guide
• Open a new issue for bugs or feature requests
• Join discussions on GitHub

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Textual
• Markdown parsing by Python-Markdown
• Command-line interface by Typer

Troubleshooting

Having issues? Check our TROUBLESHOOTING.md guide for solutions to common problems:

• Installation issues
• Pipeline/stdin problems
• Display and rendering issues
• Platform-specific issues (Windows, macOS, Linux)
• Performance problems

Quick Fixes

Command not found after install:

# Try running with python -m
python -m txmd README.md

# Or ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

No colors/syntax highlighting:

# Check terminal type
echo $TERM  # Should be something like xterm-256color

# Set if needed
export TERM=xterm-256color

Pipeline not working on Windows:

# Use WSL for full pipeline support
wsl -e txmd README.md

For more help, see the full troubleshooting guide.

FAQ

Q: Why use txmd instead of other markdown viewers? A: txmd is designed to be lightweight, fast, and integrate seamlessly with Unix pipelines while providing a beautiful TUI interface. It's perfect for developers who live in the terminal.

Q: Does txmd support custom themes? A: Not yet, but it's on our roadmap! Custom theme support is planned for v0.2.0 or later.

Q: Can I use txmd to preview markdown before committing to git? A: Absolutely! git show HEAD:README.md | txmd or git diff main...HEAD | txmd

Q: Does txmd work on Windows? A: Yes, but for best results use Windows Terminal or WSL. Pipeline support works best on Linux/macOS or WSL.

Q: Can I view multiple files at once? A: Not yet, but multi-file support with tabs is on the roadmap!

Q: How do I report a bug or request a feature? A: Open an issue on GitHub with details about the bug or feature request.

Roadmap

v0.4.0 - Table of Contents (Released)

Completed:

• Table of Contents - Dynamic TOC with hierarchical navigation
  • Hierarchical tree view of document headers
  • Toggle with 't' key
  • Navigate with arrow keys, expand/collapse with Enter, jump with Space
  • Filters headers in code blocks
• Comprehensive Testing - 84% test coverage with UI interaction tests

v0.5.0 - Enhanced Features (Planned)

In Development:

• Multi-file support - View multiple markdown files with tab navigation
• Search functionality - Find text within documents with incremental search
• Bookmark support - Mark and jump to important sections
• Custom themes - Support for custom color schemes and styling

Future Versions

Additional features planned for future releases:

• Configuration file - User preferences and custom keybindings
• GitHub Flavored Markdown - Extended markdown syntax support
• Image preview - Terminal graphics protocol support (Kitty, iTerm2)
• Export functionality - Convert to HTML, PDF
• Watch mode - Auto-reload on file changes
• Split view - View two documents side by side

See the GitHub issues and project milestones for more details.

Support

Getting Help

• 📖 Documentation: Check the docs section above
• 🐛 Bug Reports: Open an issue with details
• 💡 Feature Requests: Request features through GitHub issues
• 💬 Discussions: Join GitHub Discussions for questions and ideas
• 🔧 Troubleshooting: See TROUBLESHOOTING.md

Project Links

• Repository: https://github.com/guglielmo/txmd
• Issue Tracker: https://github.com/guglielmo/txmd/issues
• PyPI Package: https://pypi.org/project/txmd/
• Changelog: See GitHub Releases