A modern, feature-rich terminal-based Markdown viewer with pipeline support,
built with [Textual](https://github.com/Textualize/textual).
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Pipeline Usage](#pipeline-usage)
- [Navigation](#navigation)
- [Keybindings Reference](#keybindings-reference)
- [Examples](#examples)
- [Supported Markdown Features](#supported-markdown-features)
- [Documentation](#documentation)
- [Development](#development)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [License](#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:
```bash
pip install txmd
```
Or using Poetry:
```bash
poetry add txmd
```
## Usage
### Basic Usage
View a Markdown file:
```bash
txmd README.md
```
### Pipeline Usage
Pipe content to txmd:
```bash
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:
```bash
# 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](examples/) 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:
```bash
# 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](CONTRIBUTING.md)** - Detailed contribution guidelines, development setup, coding standards, and PR process
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture, design decisions, and component details
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Solutions for common issues and debugging help
- **[CLAUDE.md](CLAUDE.md)** - AI assistant context and project overview
- **[examples/](examples/)** - Sample markdown files demonstrating features
## Development
### Quick Start
1. **Clone the repository:**
```bash
git clone https://github.com/guglielmo/txmd
cd txmd
```
2. **Install Poetry** (if not already installed):
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
3. **Install dependencies:**
```bash
poetry install
```
4. **Run from source:**
```bash
poetry run txmd README.md
```
5. **Run tests:**
```bash
poetry run pytest
```
### Code Quality
```bash
# 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](CONTRIBUTING.md) and [ARCHITECTURE.md](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**:
```bash
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](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](https://github.com/guglielmo/txmd/issues)
- Read the [TROUBLESHOOTING.md](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](LICENSE) file for details.
## Acknowledgments
- Built with [Textual](https://github.com/Textualize/textual)
- Markdown parsing by [Python-Markdown](https://python-markdown.github.io/)
- Command-line interface by [Typer](https://typer.tiangolo.com/)
## Troubleshooting
Having issues? Check our [TROUBLESHOOTING.md](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:**
```bash
# 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:**
```bash
# Check terminal type
echo $TERM # Should be something like xterm-256color
# Set if needed
export TERM=xterm-256color
```
**Pipeline not working on Windows:**
```bash
# Use WSL for full pipeline support
wsl -e txmd README.md
```
For more help, see the [full troubleshooting guide](TROUBLESHOOTING.md).
## 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](https://github.com/guglielmo/txmd/issues) with details about the bug or feature request.
## Roadmap
### v0.4.0 - Table of Contents (Released)
**Completed:**
- [x] **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
- [x] **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](https://github.com/guglielmo/txmd/issues) and [project milestones](https://github.com/guglielmo/txmd/milestones) for more details.
## Support
### Getting Help
- 📖 **Documentation**: Check the [docs](#documentation) section above
- 🐛 **Bug Reports**: [Open an issue](https://github.com/guglielmo/txmd/issues/new) with details
- 💡 **Feature Requests**: [Request features](https://github.com/guglielmo/txmd/issues/new) through GitHub issues
- 💬 **Discussions**: Join [GitHub Discussions](https://github.com/guglielmo/txmd/discussions) for questions and ideas
- 🔧 **Troubleshooting**: See [TROUBLESHOOTING.md](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](https://github.com/guglielmo/txmd/releases)
Raw data
{
"_id": null,
"home_page": "https://github.com/guglielmo/txmd",
"name": "txmd",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "markdown, terminal, cli, viewer, textual",
"author": "Guglielmo Celata",
"author_email": "guglielmo.celata@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/e5/b36ef015f9801aa5c40c23edbe60fa4007cd69c55715178dd1cbd55467c2/txmd-0.4.0.tar.gz",
"platform": null,
"description": "A modern, feature-rich terminal-based Markdown viewer with pipeline support,\nbuilt with [Textual](https://github.com/Textualize/textual).\n\n\n\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Basic Usage](#basic-usage)\n - [Pipeline Usage](#pipeline-usage)\n - [Navigation](#navigation)\n - [Keybindings Reference](#keybindings-reference)\n- [Examples](#examples)\n- [Supported Markdown Features](#supported-markdown-features)\n- [Documentation](#documentation)\n- [Development](#development)\n- [Contributing](#contributing)\n- [Troubleshooting](#troubleshooting)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n## Features\n\n- \ud83d\udcdd Render Markdown files directly in your terminal\n- \ud83d\udd04 Pipeline support - pipe markdown content directly to txmd\n- \ud83d\uddc2\ufe0f **Dynamic Table of Contents** - Navigate long documents with hierarchical TOC\n- \ud83c\udfa8 Syntax highlighting for code blocks\n- \ud83d\udcca Table support\n- \ud83d\uddbc\ufe0f Beautiful TUI interface powered by Textual\n- \u2328\ufe0f Vim-style navigation (j/k for scrolling)\n- \ud83d\ude80 Fast and lightweight\n\n## Installation\n\nYou can install txmd using pip:\n\n```bash\npip install txmd\n```\n\nOr using Poetry:\n\n```bash\npoetry add txmd\n```\n\n## Usage\n\n### Basic Usage\n\nView a Markdown file:\n\n```bash\ntxmd README.md\n```\n\n### Pipeline Usage\n\nPipe content to txmd:\n\n```bash\necho \"# Hello World\" | txmd\ncat document.md | txmd\ncurl https://raw.githubusercontent.com/user/repo/main/README.md | txmd\n```\n\n### Table of Contents\n\nFor documents with headers, txmd provides a dynamic Table of Contents sidebar:\n\n**Toggle TOC:**\n- `t` - Show/hide the Table of Contents panel\n\n**Using the TOC:**\n- The TOC automatically parses all headers (# through ######) in your document\n- Headers are displayed in a hierarchical tree structure\n- Navigate with arrow keys (`\u2191`/`\u2193`) when TOC is focused\n- Press `Enter` to expand/collapse sections with subsections\n- Press `Space` to jump to the selected section (positions it at top of screen)\n- Click a header to jump directly to that section\n- Leaf sections (no subsections) have no expand icon for cleaner display\n- Hidden by default to maximize reading space\n\nThe TOC is especially useful for:\n- Long documentation files with many sections\n- README files with multiple chapters\n- Technical documentation with nested topics\n- Any structured markdown content\n\n### Navigation\n\nInside the viewer, you can navigate using vim-style keys or traditional navigation keys:\n\n**Basic Scrolling:**\n- `j` or `\u2193` - Scroll down one line\n- `k` or `\u2191` - Scroll up one line\n\n**Page Scrolling:**\n- `Space` or `Page Down` - Scroll down one page\n- `b` or `Page Up` - Scroll up one page\n\n**Jump to Position:**\n- `Home` - Jump to the top of the document\n- `End` - Jump to the bottom of the document\n\n**Exit:**\n- `q` or `Ctrl+C` - Quit the viewer\n\n### Keybindings Reference\n\nComplete list of all keybindings:\n\n| Key(s) | Action | Description |\n|--------|--------|-------------|\n| `j`, `\u2193` | Scroll Down | Move down one line |\n| `k`, `\u2191` | Scroll Up | Move up one line |\n| `Space`, `Page Down` | Page Down | Scroll down by viewport height |\n| `b`, `Page Up` | Page Up | Scroll up by viewport height |\n| `Home` | Jump to Top | Scroll to the beginning of the document |\n| `End` | Jump to Bottom | Scroll to the end of the document |\n| `t` | Toggle TOC | Show/hide Table of Contents sidebar |\n| `q`, `Ctrl+C` | Quit | Exit the application |\n\n> **Note:** All scrolling operations happen instantly without animation for a responsive feel.\n\n## Examples\n\ntxmd includes a collection of example markdown files demonstrating various features:\n\n```bash\n# View basic markdown features\ntxmd examples/basic.md\n\n# See syntax highlighting for various languages\ntxmd examples/code-blocks.md\n\n# Explore table formatting\ntxmd examples/tables.md\n\n# Check out advanced features\ntxmd examples/advanced.md\n```\n\nSee the [examples directory](examples/) for more information and sample files.\n\n## Supported Markdown Features\n\ntxmd supports all standard Markdown elements through Textual's Markdown widget:\n\n| Feature | Support | Notes |\n|---------|---------|-------|\n| **Headers** | \u2705 Full | All levels (H1-H6) |\n| **Text Formatting** | \u2705 Full | Bold, italic, strikethrough |\n| **Lists** | \u2705 Full | Ordered, unordered, nested |\n| **Code Blocks** | \u2705 Full | Syntax highlighting for 100+ languages |\n| **Inline Code** | \u2705 Full | Monospace formatting |\n| **Tables** | \u2705 Full | With column alignment |\n| **Blockquotes** | \u2705 Full | Including nested quotes |\n| **Horizontal Rules** | \u2705 Full | Visual separators |\n| **Links** | \u2705 Full | Displayed with formatting |\n| **Images** | \u26a0\ufe0f Partial | Text representation in terminal |\n\n### Code Syntax Highlighting\n\nSyntax highlighting is supported for many languages including:\n- Python, JavaScript, TypeScript, Rust, Go\n- Java, C, C++, C#, Ruby, PHP\n- Bash, Shell, PowerShell\n- HTML, CSS, SCSS, JSON, YAML, TOML, XML\n- SQL, Markdown, and many more\n\n### Pipeline Integration\n\ntxmd is designed to work seamlessly in Unix pipelines. This means you can:\n\n```bash\n# Preview markdown before committing\ngit show HEAD:README.md | txmd\n\n# View remote markdown files\ncurl -s https://raw.githubusercontent.com/user/repo/main/README.md | txmd\n\n# View markdown from any command output\necho \"# Dynamic Content\\n\\nGenerated at $(date)\" | txmd\n\n# Process and view markdown\ngrep -A 10 \"## Section\" document.md | txmd\n```\n\n**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.\n\n> **Platform Note:** Full pipeline support works on Linux and macOS. On Windows, use WSL or Windows Terminal for best results.\n\n## Documentation\n\nComprehensive documentation is available:\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Detailed contribution guidelines, development setup, coding standards, and PR process\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture, design decisions, and component details\n- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Solutions for common issues and debugging help\n- **[CLAUDE.md](CLAUDE.md)** - AI assistant context and project overview\n- **[examples/](examples/)** - Sample markdown files demonstrating features\n\n## Development\n\n### Quick Start\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/guglielmo/txmd\n cd txmd\n ```\n\n2. **Install Poetry** (if not already installed):\n ```bash\n curl -sSL https://install.python-poetry.org | python3 -\n ```\n\n3. **Install dependencies:**\n ```bash\n poetry install\n ```\n\n4. **Run from source:**\n ```bash\n poetry run txmd README.md\n ```\n\n5. **Run tests:**\n ```bash\n poetry run pytest\n ```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run black txmd/\n\n# Sort imports\npoetry run isort txmd/\n\n# Lint code\npoetry run flake8 txmd/\n\n# Run all checks\npoetry run black txmd/ && poetry run isort txmd/ && poetry run flake8 txmd/ && poetry run pytest\n```\n\n### Project Structure\n\n```\ntxmd/\n\u251c\u2500\u2500 txmd/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # Main application (CLI + TUI)\n\u2502 \u2514\u2500\u2500 toc.py # Table of Contents module\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 test_cli.py # CLI test suite\n\u2502 \u2514\u2500\u2500 test_toc.py # TOC test suite\n\u251c\u2500\u2500 examples/ # Example markdown files\n\u2502 \u251c\u2500\u2500 basic.md\n\u2502 \u251c\u2500\u2500 code-blocks.md\n\u2502 \u251c\u2500\u2500 tables.md\n\u2502 \u251c\u2500\u2500 advanced.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 CONTRIBUTING.md # Contribution guidelines\n\u251c\u2500\u2500 ARCHITECTURE.md # Technical documentation\n\u251c\u2500\u2500 TROUBLESHOOTING.md # Common issues and solutions\n\u251c\u2500\u2500 CLAUDE.md # AI assistant context\n\u251c\u2500\u2500 pyproject.toml # Poetry configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\nFor detailed development information, see [CONTRIBUTING.md](CONTRIBUTING.md) and [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## Contributing\n\nContributions are welcome and appreciated! We'd love your help making txmd better.\n\n### Quick Contribution Guide\n\n1. **Fork and clone** the repository\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** and add tests\n4. **Run quality checks**:\n ```bash\n poetry run black txmd/\n poetry run isort txmd/\n poetry run flake8 txmd/\n poetry run pytest\n ```\n5. **Commit your changes**: `git commit -m 'Add amazing feature'`\n6. **Push to your fork**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### What to Contribute\n\n- \ud83d\udc1b **Bug fixes** - Help us squash bugs\n- \u2728 **New features** - Add capabilities from the roadmap\n- \ud83d\udcdd **Documentation** - Improve or add documentation\n- \u2705 **Tests** - Increase test coverage\n- \ud83c\udfa8 **Examples** - Create new example markdown files\n\n### Before Contributing\n\nPlease read our comprehensive [CONTRIBUTING.md](CONTRIBUTING.md) guide which covers:\n- Development setup and workflow\n- Coding standards and style guide\n- Testing guidelines\n- PR process and review guidelines\n- Project architecture and structure\n\n### Getting Help\n\n- Check [existing issues](https://github.com/guglielmo/txmd/issues)\n- Read the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide\n- Open a new issue for bugs or feature requests\n- Join discussions on GitHub\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Textual](https://github.com/Textualize/textual)\n- Markdown parsing by [Python-Markdown](https://python-markdown.github.io/)\n- Command-line interface by [Typer](https://typer.tiangolo.com/)\n\n## Troubleshooting\n\nHaving issues? Check our [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide for solutions to common problems:\n\n- Installation issues\n- Pipeline/stdin problems\n- Display and rendering issues\n- Platform-specific issues (Windows, macOS, Linux)\n- Performance problems\n\n### Quick Fixes\n\n**Command not found after install:**\n```bash\n# Try running with python -m\npython -m txmd README.md\n\n# Or ensure ~/.local/bin is in PATH\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n**No colors/syntax highlighting:**\n```bash\n# Check terminal type\necho $TERM # Should be something like xterm-256color\n\n# Set if needed\nexport TERM=xterm-256color\n```\n\n**Pipeline not working on Windows:**\n```bash\n# Use WSL for full pipeline support\nwsl -e txmd README.md\n```\n\nFor more help, see the [full troubleshooting guide](TROUBLESHOOTING.md).\n\n## FAQ\n\n**Q: Why use txmd instead of other markdown viewers?**\nA: txmd is designed to be lightweight, fast, and integrate seamlessly\nwith Unix pipelines while providing a beautiful TUI interface. It's perfect for developers who live in the terminal.\n\n**Q: Does txmd support custom themes?**\nA: Not yet, but it's on our roadmap! Custom theme support is planned for v0.2.0 or later.\n\n**Q: Can I use txmd to preview markdown before committing to git?**\nA: Absolutely! `git show HEAD:README.md | txmd` or `git diff main...HEAD | txmd`\n\n**Q: Does txmd work on Windows?**\nA: Yes, but for best results use Windows Terminal or WSL. Pipeline support works best on Linux/macOS or WSL.\n\n**Q: Can I view multiple files at once?**\nA: Not yet, but multi-file support with tabs is on the roadmap!\n\n**Q: How do I report a bug or request a feature?**\nA: Open an issue on [GitHub](https://github.com/guglielmo/txmd/issues) with details about the bug or feature request.\n\n## Roadmap\n\n### v0.4.0 - Table of Contents (Released)\n\n**Completed:**\n- [x] **Table of Contents** - Dynamic TOC with hierarchical navigation\n - Hierarchical tree view of document headers\n - Toggle with 't' key\n - Navigate with arrow keys, expand/collapse with Enter, jump with Space\n - Filters headers in code blocks\n- [x] **Comprehensive Testing** - 84% test coverage with UI interaction tests\n\n### v0.5.0 - Enhanced Features (Planned)\n\n**In Development:**\n- [ ] **Multi-file support** - View multiple markdown files with tab navigation\n- [ ] **Search functionality** - Find text within documents with incremental search\n- [ ] **Bookmark support** - Mark and jump to important sections\n- [ ] **Custom themes** - Support for custom color schemes and styling\n\n### Future Versions\n\nAdditional features planned for future releases:\n\n- [ ] **Configuration file** - User preferences and custom keybindings\n- [ ] **GitHub Flavored Markdown** - Extended markdown syntax support\n- [ ] **Image preview** - Terminal graphics protocol support (Kitty, iTerm2)\n- [ ] **Export functionality** - Convert to HTML, PDF\n- [ ] **Watch mode** - Auto-reload on file changes\n- [ ] **Split view** - View two documents side by side\n\nSee the [GitHub issues](https://github.com/guglielmo/txmd/issues) and [project milestones](https://github.com/guglielmo/txmd/milestones) for more details.\n\n## Support\n\n### Getting Help\n\n- \ud83d\udcd6 **Documentation**: Check the [docs](#documentation) section above\n- \ud83d\udc1b **Bug Reports**: [Open an issue](https://github.com/guglielmo/txmd/issues/new) with details\n- \ud83d\udca1 **Feature Requests**: [Request features](https://github.com/guglielmo/txmd/issues/new) through GitHub issues\n- \ud83d\udcac **Discussions**: Join [GitHub Discussions](https://github.com/guglielmo/txmd/discussions) for questions and ideas\n- \ud83d\udd27 **Troubleshooting**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\n\n### Project Links\n\n- **Repository**: https://github.com/guglielmo/txmd\n- **Issue Tracker**: https://github.com/guglielmo/txmd/issues\n- **PyPI Package**: https://pypi.org/project/txmd/\n- **Changelog**: See [GitHub Releases](https://github.com/guglielmo/txmd/releases)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A textual markdown viewer CLI",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/guglielmo/txmd#readme",
"Homepage": "https://github.com/guglielmo/txmd",
"Repository": "https://github.com/guglielmo/txmd"
},
"split_keywords": [
"markdown",
" terminal",
" cli",
" viewer",
" textual"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9410bc2b2a5c561011ce170068a201ba34a1a040e8feca031c6e816e1ce9eeb9",
"md5": "9509ad94ff9503149c43e3e92c83f047",
"sha256": "e71ae0b5d22217c90ecfa9cbb43a9e1bb9d61066deeeffb4315b438807e1447a"
},
"downloads": -1,
"filename": "txmd-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9509ad94ff9503149c43e3e92c83f047",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 13711,
"upload_time": "2025-10-20T16:48:53",
"upload_time_iso_8601": "2025-10-20T16:48:53.637361Z",
"url": "https://files.pythonhosted.org/packages/94/10/bc2b2a5c561011ce170068a201ba34a1a040e8feca031c6e816e1ce9eeb9/txmd-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5e5b36ef015f9801aa5c40c23edbe60fa4007cd69c55715178dd1cbd55467c2",
"md5": "0c89bc36212e622625f1d50a6ff5a264",
"sha256": "ccbb661ed99eae40d7851862a11067483a248a7efa583b3d33693276305e41c0"
},
"downloads": -1,
"filename": "txmd-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "0c89bc36212e622625f1d50a6ff5a264",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 17265,
"upload_time": "2025-10-20T16:48:54",
"upload_time_iso_8601": "2025-10-20T16:48:54.635937Z",
"url": "https://files.pythonhosted.org/packages/c5/e5/b36ef015f9801aa5c40c23edbe60fa4007cd69c55715178dd1cbd55467c2/txmd-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 16:48:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guglielmo",
"github_project": "txmd",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "txmd"
}
JSON
