mdok 0.1.0__py3-none-any.whl

mdok/__init__.py

@@ -0,0 +1,4 @@
+"""mdok - Document-grade Markdown Reader for CLI."""
+
+__version__ = "0.1.0"
+

mdok/__main__.py

@@ -0,0 +1,4 @@
+from mdok.cli import main
+
+if __name__ == "__main__":
+    main()

mdok/canvas.py

@@ -0,0 +1,102 @@
+import shutil
+from dataclasses import dataclass
+from typing import Optional, Tuple
+from rich.console import Console, ConsoleOptions, RenderResult, RenderableType
+from rich.segment import Segment
+from rich.measure import Measurement
+
+
+@dataclass
+class CanvasConfig:
+    """Configuration for document canvas layout."""
+    max_width: Optional[int] = None
+    min_width: int = 70
+    cap_width: int = 124
+    ratio: float = 0.74
+    margin: Optional[int] = None
+    center: bool = True
+
+
+def calculate_dimensions(
+    terminal_width: int,
+    config: Optional[CanvasConfig] = None,
+) -> Tuple[int, int]:
+    """
+    Calculate (doc_width, left_margin) based on terminal width and config.
+
+    Rules:
+    - Narrow screens (<= 82): maximize width with minimal 2-char gutter.
+    - Medium screens (83-105): generous 80-85% width.
+    - Wide screens (> 105): proportional document sheet (~74% width) up to cap_width (default 124),
+      avoiding both full-screen blowout and artificial narrow text walls.
+    """
+    cfg = config or CanvasConfig()
+
+    if cfg.max_width is not None:
+        doc_w = min(cfg.max_width, terminal_width)
+    else:
+        if terminal_width <= 82:
+            doc_w = max(30, terminal_width - 4)
+        elif terminal_width <= 105:
+            doc_w = min(terminal_width - 6, max(76, int(terminal_width * 0.84)))
+        else:
+            proportional = int(terminal_width * cfg.ratio)
+            doc_w = min(cfg.cap_width, max(88, proportional))
+            doc_w = min(doc_w, terminal_width - 12)
+
+    doc_w = max(20, min(doc_w, terminal_width))
+
+    if cfg.margin is not None:
+        left_margin = max(0, min(cfg.margin, terminal_width - doc_w))
+    elif cfg.center:
+        left_margin = max(0, (terminal_width - doc_w) // 2)
+    else:
+        left_margin = 0
+
+    return doc_w, left_margin
+
+
+class DocumentCanvas:
+    """
+    Renders a renderable constrained to `doc_width` and indented by `left_margin`.
+    This provides a centered 'sheet of paper' reading experience.
+    """
+
+    def __init__(
+        self,
+        renderable: RenderableType,
+        doc_width: int,
+        left_margin: int,
+    ) -> None:
+        self.renderable = renderable
+        self.doc_width = doc_width
+        self.left_margin = left_margin
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        if getattr(self.renderable, "has_canvas_layout", False):
+            # Renderable manages its own margins and widths (including table breakout)
+            yield from console.render(self.renderable, options)
+            return
+
+        # Constrain the inner document to doc_width
+        doc_options = options.update_width(self.doc_width)
+        lines = console.render_lines(self.renderable, doc_options, pad=False)
+
+        margin_prefix = " " * self.left_margin if self.left_margin > 0 else ""
+        margin_segment = Segment(margin_prefix) if margin_prefix else None
+
+        for line in lines:
+            if margin_segment and line:
+                yield margin_segment
+                for segment in line:
+                    yield segment
+                yield Segment.line()
+            elif margin_segment and not line:
+                # Blank line
+                yield Segment.line()
+            else:
+                for segment in line:
+                    yield segment
+                yield Segment.line()

mdok/cli.py

@@ -0,0 +1,169 @@
+import argparse
+import sys
+import os
+import shutil
+from typing import Optional, List
+from rich.console import Console
+from rich.theme import Theme
+
+from mdok import __version__
+from mdok.theme import DEFAULT_THEME, BOX_STYLES
+from mdok.canvas import CanvasConfig, calculate_dimensions, DocumentCanvas
+from mdok.renderer import DocMarkdown
+
+
+def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="mdok",
+        description="Document-grade Markdown Reader for the terminal.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        default="-",
+        help="Markdown file to read, or '-' for standard input (default: '-')",
+    )
+    parser.add_argument(
+        "-w",
+        "--width",
+        type=int,
+        default=None,
+        help="Max document reading width (default: auto ~88 chars on wide displays)",
+    )
+    parser.add_argument(
+        "-m",
+        "--margin",
+        type=int,
+        default=None,
+        help="Explicit left margin in columns (default: auto-centered)",
+    )
+    parser.add_argument(
+        "--no-center",
+        action="store_true",
+        help="Disable centering and align to left edge",
+    )
+    parser.add_argument(
+        "-b",
+        "--box",
+        choices=list(BOX_STYLES.keys()),
+        default="booktabs",
+        help="Table box style: booktabs (default), minimal, rounded, simple, simple_head, none",
+    )
+    parser.add_argument(
+        "--no-lines",
+        action="store_true",
+        help="Hide horizontal row divider lines in tables",
+    )
+    parser.add_argument(
+        "--code-theme",
+        default="nord",
+        help="Pygments code syntax highlighting theme (default: nord)",
+    )
+    parser.add_argument(
+        "-p",
+        "--pager",
+        action="store_true",
+        default=None,
+        help="Force output through pager (less -RFX)",
+    )
+    parser.add_argument(
+        "--no-pager",
+        action="store_true",
+        help="Disable pager and print directly to terminal",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser.parse_args(args)
+
+
+def read_content(file_arg: str) -> str:
+    if file_arg == "-":
+        if sys.stdin.isatty():
+            # Nothing piped and stdin is a tty
+            return ""
+        return sys.stdin.read()
+    
+    path = os.path.expanduser(file_arg)
+    if not os.path.exists(path):
+        sys.stderr.write(f"Error: file not found: {file_arg}\n")
+        sys.exit(1)
+    
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parse_args(argv)
+
+    content = read_content(args.file)
+    if not content:
+        if args.file == "-":
+            sys.stderr.write("mdok: no input provided via stdin or file. Use 'mdok --help' for usage.\n")
+            return 1
+        return 0
+
+    # Determine terminal dimensions
+    is_tty = sys.stdout.isatty()
+    term_width, term_height = shutil.get_terminal_size(fallback=(100, 24))
+
+    # Canvas layout calculations
+    config = CanvasConfig(
+        max_width=args.width,
+        margin=args.margin,
+        center=not args.no_center if is_tty else False,
+    )
+    doc_width, left_margin = calculate_dimensions(term_width, config)
+
+    # If piped to another process (not a tty) and user didn't specify width/margin,
+    # don't pad with left margin
+    if not is_tty and args.margin is None and not args.no_center:
+        left_margin = 0
+
+    # Build document
+    markdown_doc = DocMarkdown(
+        content,
+        code_theme=args.code_theme,
+        box_style=args.box,
+        show_lines=not args.no_lines,
+        doc_width=doc_width,
+        left_margin=left_margin,
+        term_width=term_width,
+    )
+
+    canvas = DocumentCanvas(
+        renderable=markdown_doc,
+        doc_width=doc_width,
+        left_margin=left_margin,
+    )
+
+    console = Console(theme=DEFAULT_THEME, width=term_width)
+
+    # Determine whether to page
+    use_pager = False
+    if is_tty:
+        if args.no_pager:
+            use_pager = False
+        elif args.pager:
+            use_pager = True
+        else:
+            # Auto-pager heuristic: estimate rendered line count
+            # Measure rendered lines
+            line_count = sum(1 for _ in console.render_lines(canvas, console.options))
+            if line_count > term_height - 2:
+                use_pager = True
+
+    if use_pager:
+        with console.pager(styles=True):
+            console.print(canvas)
+    else:
+        console.print(canvas)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mdok/renderer.py

@@ -0,0 +1,632 @@
+import re
+from typing import ClassVar, Dict, List, Optional, Tuple, Union
+from rich.box import Box
+from rich.cells import cell_len
+from rich.console import Console, ConsoleOptions, RenderResult, Group
+from rich.markdown import (
+    Markdown,
+    MarkdownContext,
+    MarkdownElement,
+    MarkdownIt,
+    TableBodyElement,
+    TableHeaderElement,
+    TableRowElement,
+    TableDataElement,
+    Paragraph,
+    BlockQuote,
+    Heading,
+    Link,
+    UnknownElement,
+)
+from rich.segment import Segment
+from rich.table import Table
+from rich.text import Text, TextType
+from rich.panel import Panel
+from rich.style import Style
+
+from mdok.theme import BOOKTABS, BOX_STYLES
+
+
+def calculate_smart_column_widths(
+    headers: List[str],
+    rows: List[List[str]],
+    available_width: int,
+) -> List[int]:
+    """
+    Calculates balanced column widths using non-linear volume-weighted allocation.
+
+    - Every column is guaranteed at least its longest unbreakable token + padding
+      (atomic badge & token preservation).
+    - Unwrapped ideal widths are respected (tables that fit stay compact).
+    - Surplus space is distributed via a continuous utility function weighted by
+      information volume (total text / rows), ensuring prose/description columns
+      receive comfortable reading widths without inflating short token columns.
+    """
+    col_count = len(headers)
+    if col_count == 0:
+        return []
+    if col_count == 1:
+        return [max(3, available_width)]
+
+    min_widths = [0] * col_count
+    ideal_widths = [0] * col_count
+    total_lens = [0] * col_count
+
+    num_rows = max(1, len(rows))
+
+    badge_pattern = re.compile(r"^([\u2600-\u27bf\U0001f300-\U0001f9ff]\s*\S+)")
+
+    def _token_min(word: str) -> int:
+        subparts = [p for p in re.split(r"[-/]", word) if p]
+        if subparts:
+            return max(cell_len(p) for p in subparts)
+        return cell_len(word)
+
+    for c in range(col_count):
+        h_text = headers[c] if c < len(headers) else ""
+        body_cells = [r[c] if c < len(r) else "" for r in rows]
+
+        b_min = 2
+        badge_min = 0
+        body_ideal = 0
+        body_tot = 0
+        has_body_content = False
+
+        # Measure body cells: body cells define ideal width, volume, and primary min-content
+        for cell in body_cells:
+            plain = str(cell)
+            cell_length = cell_len(plain)
+            if cell_length > 0:
+                has_body_content = True
+            body_tot += cell_length
+            lines = plain.split("\n")
+            for line in lines:
+                body_ideal = max(body_ideal, cell_len(line))
+                badge_m = badge_pattern.match(line.strip())
+                if badge_m:
+                    badge_min = max(badge_min, cell_len(badge_m.group(1)))
+                for word in line.split():
+                    # Token min length, capped at 13 so code signatures don't starve other columns
+                    b_min = max(b_min, min(_token_min(word), 13))
+
+        # Measure header: header sets wrap boundary, but does not dictate width
+        # if body content is sparse (headers can wrap / fold)
+        h_min = 2
+        h_ideal = 0
+        h_plain = str(h_text)
+        for line in h_plain.split("\n"):
+            h_ideal = max(h_ideal, cell_len(line))
+            badge_m = badge_pattern.match(line.strip())
+            if badge_m:
+                badge_min = max(badge_min, cell_len(badge_m.group(1)))
+            for word in line.split():
+                h_min = max(h_min, min(_token_min(word), 13))
+
+        if has_body_content:
+            # Atomic badges must never be split. Body tokens and header tokens set min width.
+            # Long header tokens fold if body is sparse.
+            col_min = max(badge_min, b_min, h_min)
+            min_widths[c] = col_min
+            ideal_widths[c] = max(min_widths[c], body_ideal, h_ideal)
+            total_lens[c] = body_tot
+        else:
+            col_min = max(badge_min, h_min, 3)
+            min_widths[c] = col_min
+            ideal_widths[c] = max(min_widths[c], h_ideal)
+            total_lens[c] = cell_len(h_plain)
+
+    total_ideal = sum(ideal_widths)
+    if total_ideal <= available_width:
+        return ideal_widths
+
+    sum_min = sum(min_widths)
+    if sum_min >= available_width:
+        deficit = sum_min - available_width
+        allocated = list(min_widths)
+        while deficit > 0:
+            candidates = [c for c in range(col_count) if allocated[c] > 3]
+            if not candidates:
+                break
+            best_c = max(candidates, key=lambda c: (allocated[c], -c))
+            allocated[best_c] -= 1
+            deficit -= 1
+        return allocated
+
+    surplus = available_width - sum_min
+    extra_wanted = [ideal_widths[c] - min_widths[c] for c in range(col_count)]
+
+    # Continuous volume-weighted utility function
+    # Columns with high text volume (narratives, descriptions) receive the lion's share
+    # of surplus width, while short token columns remain compact.
+    weights = []
+    for c in range(col_count):
+        if extra_wanted[c] <= 0:
+            weights.append(0.0)
+        else:
+            avg_vol = total_lens[c] / (num_rows + 1)
+            weights.append(extra_wanted[c] * (avg_vol ** 1.5))
+
+    sum_weights = sum(weights) or 1.0
+
+    allocated = list(min_widths)
+    for c in range(col_count):
+        if weights[c] > 0:
+            share = int(surplus * (weights[c] / sum_weights))
+            allocated[c] += min(share, extra_wanted[c])
+
+    remainder = available_width - sum(allocated)
+    while remainder > 0:
+        candidates = [
+            (total_lens[c], extra_wanted[c] - (allocated[c] - min_widths[c]), c)
+            for c in range(col_count)
+            if (allocated[c] - min_widths[c]) < extra_wanted[c]
+        ]
+        if not candidates:
+            best_c = max(range(col_count), key=lambda c: total_lens[c])
+            allocated[best_c] += remainder
+            break
+        candidates.sort(reverse=True)
+        _, can_add, best_c = candidates[0]
+        step = min(remainder, max(1, can_add))
+        allocated[best_c] += step
+        remainder -= step
+
+    diff = available_width - sum(allocated)
+    if diff != 0:
+        best_c = max(range(col_count), key=lambda c: total_lens[c])
+        allocated[best_c] = max(3, allocated[best_c] + diff)
+
+    return allocated
+
+
+class DocTableElement(MarkdownElement):
+    """
+    Enhanced Table element with:
+    - Clean Booktabs borders (or configurable box style)
+    - Row separation lines to prevent multi-line rows fusing together
+    - Respected column alignments (left, center, right)
+    - Soft word wrapping without breaking layout
+    - Smart column width budgeting (wide tables don't vertically collapse)
+    """
+
+    box_style: ClassVar[Box] = BOOKTABS
+    show_lines: ClassVar[bool] = True
+
+    def __init__(self) -> None:
+        self.header: Optional[TableHeaderElement] = None
+        self.body: Optional[TableBodyElement] = None
+
+    def on_child_close(self, context: MarkdownContext, child: MarkdownElement) -> bool:
+        if isinstance(child, TableHeaderElement):
+            self.header = child
+        elif isinstance(child, TableBodyElement):
+            self.body = child
+        else:
+            raise RuntimeError(f"Unexpected child in table: {type(child)}")
+        return False
+
+    def get_column_data(self) -> Tuple[List[str], List[List[str]]]:
+        headers: List[str] = []
+        if self.header is not None and self.header.row is not None:
+            for cell in self.header.row.cells:
+                headers.append(cell.content.plain)
+        elif self.body is not None and self.body.rows:
+            headers = [f"Col {i+1}" for i in range(len(self.body.rows[0].cells))]
+
+        rows: List[List[str]] = []
+        if self.body is not None:
+            for row in self.body.rows:
+                rows.append([cell.content.plain for cell in row.cells])
+        return headers, rows
+
+    def get_ideal_width(self) -> int:
+        headers, rows = self.get_column_data()
+        col_count = len(headers)
+        if col_count == 0:
+            return 0
+        ideal_widths = [0] * col_count
+        for c in range(col_count):
+            h_text = headers[c] if c < len(headers) else ""
+            all_cells = [h_text] + [r[c] if c < len(r) else "" for r in rows]
+            c_ideal = 2
+            for cell in all_cells:
+                plain = str(cell)
+                for line in plain.split("\n"):
+                    c_ideal = max(c_ideal, cell_len(line))
+            ideal_widths[c] = c_ideal + 2
+        extra = max(0, col_count - 1)
+        return sum(ideal_widths) + extra
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        table = Table(
+            box=self.box_style,
+            show_lines=self.show_lines,
+            pad_edge=False,
+            style="markdown.table.border",
+            show_edge=False,
+            collapse_padding=False,
+            padding=(0, 1),
+            expand=False,
+        )
+
+        headers, rows = self.get_column_data()
+        column_count = len(headers)
+
+        if self.header is not None and self.header.row is not None:
+            for cell in self.header.row.cells:
+                heading = cell.content.copy()
+                heading.stylize("markdown.table.header")
+                justify = getattr(cell, "justify", "left")
+                table.add_column(
+                    heading,
+                    justify=justify,
+                    overflow="fold",
+                    no_wrap=False,
+                )
+        elif self.body is not None and self.body.rows:
+            for cell in self.body.rows[0].cells:
+                justify = getattr(cell, "justify", "left")
+                table.add_column(justify=justify, overflow="fold", no_wrap=False)
+
+        if self.body is not None:
+            for row in self.body.rows:
+                row_content = [cell.content for cell in row.cells]
+                while len(row_content) < column_count:
+                    row_content.append(Text(""))
+                table.add_row(*row_content[:column_count])
+
+        # Apply smart column widths
+        if column_count > 0:
+            extra = table._extra_width
+            total_padding = sum(table._get_padding_width(i) for i in range(column_count))
+            avail = max(column_count * 3, options.max_width - extra - total_padding)
+            col_widths = calculate_smart_column_widths(headers, rows, avail)
+            for col, w in zip(table.columns, col_widths):
+                col.width = w
+
+        yield Text("")  # Spacing before table
+        yield table
+        yield Text("")  # Spacing after table
+
+
+BR_PATTERN = re.compile(r"(?i)<br\s*/?>")
+
+
+class DocTableDataElement(TableDataElement):
+    """
+    Table data cell supporting <br>, <br/>, <br /> HTML line breaks
+    inside table cells.
+    """
+
+    def on_text(self, context: MarkdownContext, text: TextType) -> None:
+        code_style = context.console.get_style("markdown.code", default=None)
+        is_code = code_style is not None and context.current_style == code_style
+        if isinstance(text, str) and not is_code:
+            parts = BR_PATTERN.split(text)
+            if len(parts) > 1:
+                for i, part in enumerate(parts):
+                    if i > 0:
+                        self.content.append("\n")
+                    if part:
+                        self.content.append(part, context.current_style)
+                return
+            self.content.append(text, context.current_style)
+        elif isinstance(text, str):
+            self.content.append(text, context.current_style)
+        else:
+            self.content.append_text(text)
+
+
+class DocParagraph(Paragraph):
+    """
+    Paragraph supporting <br>, <br/>, <br /> HTML line breaks.
+    """
+
+    def on_text(self, context: MarkdownContext, text: TextType) -> None:
+        code_style = context.console.get_style("markdown.code", default=None)
+        is_code = code_style is not None and context.current_style == code_style
+        if isinstance(text, str) and not is_code:
+            parts = BR_PATTERN.split(text)
+            if len(parts) > 1:
+                for i, part in enumerate(parts):
+                    if i > 0:
+                        self.text.append("\n")
+                    if part:
+                        self.text.append(part, context.current_style)
+                return
+            self.text.append(text, context.current_style)
+        elif isinstance(text, str):
+            self.text.append(text, context.current_style)
+        else:
+            self.text.append_text(text)
+
+
+
+
+ALERT_TYPES = {
+    "[!NOTE]": ("NOTE", "cyan", "ℹ"),
+    "[!TIP]": ("TIP", "green", "💡"),
+    "[!IMPORTANT]": ("IMPORTANT", "magenta", "★"),
+    "[!WARNING]": ("WARNING", "#e0af68", "⚠"),
+    "[!CAUTION]": ("CAUTION", "red", "✖"),
+}
+
+
+
+class DocBlockQuote(BlockQuote):
+    """
+    Enhanced blockquote supporting GitHub-style alert callouts:
+    > [!NOTE]
+    > [!TIP]
+    > [!WARNING]
+    > [!IMPORTANT]
+    > [!CAUTION]
+    """
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        # Check if blockquote starts with an alert marker
+        raw_text = ""
+        for el in self.elements:
+            if hasattr(el, "text"):
+                raw_text = str(el.text).strip()
+                break
+
+        first_word = raw_text.split()[0].upper() if raw_text else ""
+        if first_word in ALERT_TYPES:
+            label, color, icon = ALERT_TYPES[first_word]
+            # Strip the marker prefix from the first element's text
+            for el in self.elements:
+                if hasattr(el, "text") and hasattr(el.text, "plain"):
+                    idx = el.text.plain.upper().find(first_word)
+                    if idx != -1:
+                        cut = idx + len(first_word)
+                        # Slice text past marker and strip leading space
+                        stripped_plain = el.text.plain[cut:].lstrip()
+                        el.text = Text(stripped_plain)
+                    break
+
+            content_renderables = list(self.elements)
+            panel = Panel(
+                Group(*content_renderables),
+                title=f"[{color} bold]{icon} {label}[/]",
+                title_align="left",
+                border_style=f"dim {color}",
+                padding=(0, 1),
+            )
+            yield panel
+        else:
+            # Fall back to standard blockquote rendering
+            yield from super().__rich_console__(console, options)
+
+
+class DocMarkdown(Markdown):
+    """
+    Markdown renderer configured with document-grade elements and smart wide table breakout.
+    """
+    elements = Markdown.elements.copy()
+    elements["table_open"] = DocTableElement
+    elements["td_open"] = DocTableDataElement
+    elements["th_open"] = DocTableDataElement
+    elements["paragraph_open"] = DocParagraph
+    elements["blockquote_open"] = DocBlockQuote
+
+    def __init__(
+        self,
+        markup: str,
+        code_theme: str = "nord",
+        box_style: str = "booktabs",
+        show_lines: bool = True,
+        doc_width: Optional[int] = None,
+        left_margin: int = 0,
+        term_width: Optional[int] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(markup, code_theme=code_theme, **kwargs)
+        # Parse with html_inline and html_block disabled so technical tags
+        # (like C++ templates <Tag> or XML tags <HAS-SETTER>) are preserved as plain text
+        parser = (
+            MarkdownIt()
+            .enable("strikethrough")
+            .enable("table")
+            .disable("html_inline", "html_block")
+        )
+        self.parsed = parser.parse(markup)
+
+        # Configure table box style and row separation
+        selected_box = BOX_STYLES.get(box_style, BOOKTABS)
+        DocTableElement.box_style = selected_box
+        DocTableElement.show_lines = show_lines
+
+        self.doc_width = doc_width
+        self.left_margin = left_margin
+        self.term_width = term_width or doc_width
+        self.has_canvas_layout = doc_width is not None
+
+    def _render_top_element(
+        self,
+        console: Console,
+        options: ConsoleOptions,
+        element: MarkdownElement,
+        need_new_line: bool,
+        new_line_segment: Segment,
+    ) -> RenderResult:
+        if need_new_line:
+            yield new_line_segment
+
+        # Check for table breakout
+        if isinstance(element, DocTableElement) and self.doc_width is not None:
+            ideal_w = element.get_ideal_width()
+            if ideal_w > self.doc_width:
+                # Table wants more width than the standard document column.
+                # Allow a moderate breakout to prevent suffocated columns, but strictly
+                # cap it to a human-readable width (max 136 cols) to avoid unreadable
+                # edge-to-edge blowout across ultrawide monitors.
+                term_w = self.term_width or self.doc_width
+                readable_table_cap = max(self.doc_width, 136)
+                max_table_w = min(readable_table_cap, max(self.doc_width, term_w - 6))
+                target_w = min(ideal_w, max_table_w)
+                target_margin = max(0, (term_w - target_w) // 2)
+                elem_options = options.update_width(target_w)
+                elem_margin = target_margin
+            else:
+                elem_options = options.update_width(self.doc_width)
+                elem_margin = self.left_margin
+        elif self.doc_width is not None:
+            elem_options = options.update_width(self.doc_width)
+            elem_margin = self.left_margin
+        else:
+            elem_options = options
+            elem_margin = 0
+
+        lines = console.render_lines(element, elem_options, pad=False)
+        margin_prefix = " " * elem_margin if elem_margin > 0 else ""
+        margin_segment = Segment(margin_prefix) if margin_prefix else None
+
+        for line in lines:
+            if margin_segment and line:
+                yield margin_segment
+                for seg in line:
+                    yield seg
+                yield Segment.line()
+            elif not line:
+                yield Segment.line()
+            else:
+                for seg in line:
+                    yield seg
+                yield Segment.line()
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        """Render markdown to the console, with breakout support for wide tables."""
+        if not self.has_canvas_layout:
+            yield from super().__rich_console__(console, options)
+            return
+
+        style = console.get_style(self.style, default="none")
+        options = options.update(height=None)
+        context = MarkdownContext(
+            console,
+            options,
+            style,
+            inline_code_lexer=self.inline_code_lexer,
+            inline_code_theme=self.inline_code_theme,
+        )
+        tokens = self.parsed
+        inline_style_tags = self.inlines
+        new_line = False
+        _new_line_segment = Segment.line()
+
+        for token in self._flatten_tokens(tokens):
+            node_type = token.type
+            tag = token.tag
+
+            entering = token.nesting == 1
+            exiting = token.nesting == -1
+            self_closing = token.nesting == 0
+
+            if node_type == "text":
+                context.on_text(token.content, node_type)
+            elif node_type == "hardbreak":
+                context.on_text("\n", node_type)
+            elif node_type == "softbreak":
+                context.on_text(" ", node_type)
+            elif node_type == "link_open":
+                href = str(token.attrs.get("href", ""))
+                if self.hyperlinks:
+                    link_style = console.get_style("markdown.link_url", default="none")
+                    link_style += Style(link=href)
+                    context.enter_style(link_style)
+                else:
+                    context.stack.push(Link.create(self, token))
+            elif node_type == "html_inline":
+                if token.content == "<kbd>":
+                    kbd_style = console.get_style("markdown.kbd", default="bold")
+                    context.enter_style(kbd_style)
+                elif token.content == "</kbd>":
+                    context.leave_style()
+                else:
+                    continue
+            elif node_type == "link_close":
+                if self.hyperlinks:
+                    context.leave_style()
+                else:
+                    element = context.stack.pop()
+                    assert isinstance(element, Link)
+                    link_style = console.get_style("markdown.link", default="none")
+                    context.enter_style(link_style)
+                    context.on_text(element.text.plain, node_type)
+                    context.leave_style()
+                    context.on_text(" (", node_type)
+                    link_url_style = console.get_style(
+                        "markdown.link_url", default="none"
+                    )
+                    context.enter_style(link_url_style)
+                    context.on_text(element.href, node_type)
+                    context.leave_style()
+                    context.on_text(")", node_type)
+            elif (
+                tag in inline_style_tags
+                and node_type != "fence"
+                and node_type != "code_block"
+            ):
+                if entering:
+                    context.enter_style(f"markdown.{tag}")
+                elif exiting:
+                    context.leave_style()
+                else:
+                    context.enter_style(f"markdown.{tag}")
+                    if token.content:
+                        context.on_text(token.content, node_type)
+                    context.leave_style()
+            else:
+                element_class = self.elements.get(token.type) or UnknownElement
+                element = element_class.create(self, token)
+
+                if entering or self_closing:
+                    context.stack.push(element)
+                    element.on_enter(context)
+
+                if exiting:
+                    element = context.stack.pop()
+                    should_render = not context.stack or (
+                        context.stack
+                        and context.stack.top.on_child_close(context, element)
+                    )
+                    if should_render:
+                        if not context.stack:
+                            yield from self._render_top_element(
+                                console, options, element, new_line, _new_line_segment
+                            )
+                        else:
+                            if new_line:
+                                yield _new_line_segment
+                            yield from console.render(element, context.options)
+                elif self_closing:
+                    context.stack.pop()
+                    text = token.content
+                    if text is not None:
+                        element.on_text(context, text)
+
+                    should_render = (
+                        not context.stack
+                        or context.stack
+                        and context.stack.top.on_child_close(context, element)
+                    )
+                    if should_render:
+                        if not context.stack:
+                            yield from self._render_top_element(
+                                console, options, element, new_line and node_type != "inline", _new_line_segment
+                            )
+                        else:
+                            if new_line and node_type != "inline":
+                                yield _new_line_segment
+                            yield from console.render(element, context.options)
+
+                if exiting or self_closing:
+                    element.on_leave(context)
+                    new_line = element.new_line

mdok/theme.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from typing import Dict
+from rich import box
+from rich.box import Box
+from rich.theme import Theme
+
+# Clean Booktabs Box: top rule, header separator, bottom rule, no vertical bars.
+BOOKTABS = box.HORIZONTALS
+
+BOX_STYLES: Dict[str, Box] = {
+    "booktabs": box.HORIZONTALS,
+    "simple": box.SIMPLE,
+    "simple_head": box.SIMPLE_HEAD,
+    "minimal": box.MINIMAL,
+    "rounded": box.ROUNDED,
+    "none": box.ASCII,
+}
+
+# Subtle, elegant document theme (not neon/flashy)
+DEFAULT_THEME = Theme({
+    "markdown.h1": "bold bright_white underline",
+    "markdown.h1.border": "dim cyan",
+    "markdown.h2": "bold cyan",
+    "markdown.h3": "bold white",
+    "markdown.h4": "bold dim white",
+    "markdown.h5": "italic dim white",
+    "markdown.h6": "dim white",
+    "markdown.hr": "dim bright_black",
+    "markdown.item.bullet": "cyan",
+    "markdown.item.number": "dim cyan",
+    "markdown.block_quote": "dim italic white",
+    "markdown.block_quote.border": "dim cyan",
+    "markdown.link": "underline cyan",
+    "markdown.link_url": "dim underline bright_blue",
+    "markdown.table.border": "dim bright_black",
+    "markdown.table.header": "bold white",
+    "markdown.code": "#e0af68 on grey15",
+    "markdown.code_block": "none",
+})

mdok-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: mdok
+Version: 0.1.0
+Summary: A document-grade terminal markdown reader with responsive centering and clean tables
+Author: Anton
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/anton/mdok
+Project-URL: Repository, https://github.com/anton/mdok
+Project-URL: Issues, https://github.com/anton/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 small CLI tool for reading Markdown 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.
+
+`mdok` formats Markdown like a clean document:
+
+- **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**: Pipes into `less` (with colors preserved) when the document is longer than your terminal screen.
+- **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 file:
+
+```bash
+mdok README.md
+```
+
+Pipe from standard input:
+
+```bash
+cat doc.md | mdok
+```
+
+### Options
+
+```bash
+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 --no-pager                # Print directly without pager
+```

mdok-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mdok/__init__.py,sha256=3DmJIMFmyvDA3TIO0X8ftOpmsvoCzgxD6RbLSsCNvSo,77
+mdok/__main__.py,sha256=e-fUh0TrFsGxvW6tvN5HHkwH7N7KsJDA1mr8vX3c40M,65
+mdok/canvas.py,sha256=0vxS2EPhTwHT-uvKszY9W67EklvO4kn0Z7wT2KedeHA,3389
+mdok/cli.py,sha256=wBpYWk0Ux8_SnS4RJzDXkkF6R0ZQ7BkJv-w7RUBK_IM,4727
+mdok/renderer.py,sha256=H-h3bgYtQfIPs71x1059JWfa4ghiF_15x_pso_tusSk,24014
+mdok/theme.py,sha256=riezBkRNDKIFuxrWG4GcVEN6vG4hy2t6E-bGbdjFYdY,1262
+mdok-0.1.0.dist-info/licenses/LICENSE,sha256=xSlh7azZEQWT03SoSqJ5yebQGWp-pTjrjjjIkHvLDj0,1062
+mdok-0.1.0.dist-info/METADATA,sha256=VRK-_c9ne9HsxMdKvhqfez3tgijojkoTNfjE7Enh-Ds,3281
+mdok-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mdok-0.1.0.dist-info/entry_points.txt,sha256=c63inRY8L9d9lkYyYNGOTNBSXQJMua6gNdMxe-BWTfM,59
+mdok-0.1.0.dist-info/top_level.txt,sha256=aIxj9ER-bkM8dgzZbf4zReorcG1dNmcTVn-952oMmQI,5
+mdok-0.1.0.dist-info/RECORD,,

mdok-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mdok-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mda = mdok.cli:main
+mdok = mdok.cli:main

mdok-0.1.0.dist-info/licenses/LICENSE

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

mdok-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mdok