Metadata-Version: 2.4
Name: mdok
Version: 0.1.3
Summary: A document-grade terminal markdown reader with responsive centering and clean tables
Author: Anton
License-Expression: MIT
Project-URL: Homepage, https://github.com/aautushka/mdok
Project-URL: Repository, https://github.com/aautushka/mdok
Project-URL: Issues, https://github.com/aautushka/mdok/issues
Keywords: markdown,terminal,cli,reader,rich,viewer,booktabs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: pygments>=2.15.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# mdok

A document-grade reader for Markdown and Word (`.docx`) files in the terminal.

Most terminal renderers either stretch text across the entire display width or force it into a rigid, narrow column on the left edge. Tables often fuse rows together, eat technical tags like `<Type>`, or ignore `<br>` line breaks. Word documents (`.docx`) piped through pandoc turn into broken ASCII grids, raw `[tags]{.underline}`, and corrupted multi-column tables.

`mdok` formats Markdown and Word documents like clean, readable documents:

- **Word (`.docx`) Reader**: Native OpenXML parser built with Python's standard library (zero heavy binary dependencies). Cleanly renders contracts, agreements, technical specifications, and resumes:
  - **Tables**: Column width allocation via `<w:tblGrid>`, multi-column cell spans (`<w:gridSpan>`), cell background shading (`<w:shd>`), and header rows (`<w:tblHeader>`).
  - **Borderless Layout Tables**: Intelligently renders side-by-side signature and party metadata blocks without ugly grid lines.
  - **Checkboxes & Form Controls**: Structured document checkboxes (`☑` / `☐`) and Wingdings symbols.
  - **Footnotes & Endnotes**: Clean inline citations with reference sections rendered at the bottom.
  - **Try it**: `mdok examples/showcase.docx` or `mdok examples/showcase.md`.
- **Proportional width & centering**: Centers text on wide displays with gentle margins and scales comfortably (~75% of terminal width up to ~120 columns).
- **Readable tables**: LaTeX *booktabs* style—horizontal rules, no heavy ASCII borders, soft cell wrapping, alignment support, and row dividers so multiline rows don't run together.
- **Tag & line break handling**: Preserves technical tags (like `<Tag>` or `<Property>`) and respects `<br>` breaks inside cells.
- **Muted colors**: Inline code uses a warm amber (`#e0af68`) on a subtle dark badge instead of bright yellow. Code blocks default to the Nord syntax theme.
- **Automatic pager with Vim navigation**: Seamless cursor-based reading in Neovim/Vim with text cursor, or tuned `less` with smart-case search and centered matches.
- **GitHub-style callouts**: Renders `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, etc.

---

## Installation

```bash
pip install mdok
```

Or from source:

```bash
git clone https://github.com/anton/mdok.git
cd mdok
pip install .
```

For development:

```bash
pip install -e .
```

---

## Usage

Read a Markdown or Word document:

```bash
mdok README.md
mdok contract.docx
```

Pipe from standard input:

```bash
cat doc.md | mdok
cat agreement.docx | mdok
```

Jump directly to a search match:

```bash
mdok doc.md -s "Installation"
mdok contract.docx -s "Termination"
```

### Options

```bash
mdok doc.md -s "Installation"         # Jump directly to search pattern and highlight
mdok doc.md -w 100                    # Explicit document width in columns
mdok doc.md -m 4                      # Explicit left margin
mdok doc.md --no-center               # Align to left edge
mdok doc.md -b rounded                # Table style (booktabs, rounded, simple, minimal, none)
mdok doc.md --code-theme gruvbox-dark # Syntax highlighting theme
mdok doc.md --nvim                    # Force Neovim viewer (true text cursor, libvterm)
mdok doc.md --vim                     # Force Vim viewer (+terminal mode with text cursor)
mdok doc.md --less                    # Force tuned less pager
mdok doc.md --no-pager                # Print directly without pager
mdok doc.md --pager-cmd "bat -p"      # Custom pager command (or use $MDOK_PAGER / $PAGER)
```

### Viewer Engine & Graceful Degradation

`mdok` automatically selects the best available viewer engine for your system:

1. **Neovim (`nvim`)**: If installed, launches in Neovim terminal mode with full 24-bit truecolor fidelity and a **real text cursor** that moves through the document.
2. **Vim (`vim`)**: If `nvim` is absent, detects if Vim is installed with `+terminal` support.
3. **Tuned `less`**: If neither is installed, gracefully degrades to `less` with smart-case search, vertical centering (`-j.5`), left gutter hit marks (`-J`), and vivid highlights (`-DSkY`).
4. **Standard Output**: If no pager binary is found, prints directly to stdout with zero errors.

### Navigation & Search

When viewing documents in `mdok`'s cursor viewer:

| Key | Action |
| --- | --- |
| `h` / `j` / `k` / `l` or Arrows | Move cursor left / down / up / right |
| `w` / `b` | Hop forward / backward word-by-word |
| `0` / `$` | Jump to beginning / end of line |
| `d` / `u` or `Ctrl-D` / `Ctrl-U` | Half-page down / up |
| `g` / `G` | Jump to top / bottom of document |
| `/pattern` / `?pattern` | Search forward / backward |
| `n` / `N` | Next / previous match (cursor lands directly on the match) |
| `v` / `V` then `y` | Visual select and yank text directly to system clipboard |
| `yy` | Yank current line directly to system clipboard |
| `yw` / `yip` | Yank word / paragraph to system clipboard |
| Mouse drag + `y` | Select with mouse and yank to system clipboard |
| `e` | Open source markdown file for editing |
| `q` | Exit |
