mdok 0.1.0__tar.gz

mdok-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,63 @@
+# 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/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mdok"
+version = "0.1.0"
+description = "A document-grade terminal markdown reader with responsive centering and clean tables"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Anton" }
+]
+keywords = [
+    "markdown",
+    "terminal",
+    "cli",
+    "reader",
+    "rich",
+    "viewer",
+    "booktabs",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "rich>=13.0.0",
+    "markdown-it-py>=3.0.0",
+    "pygments>=2.15.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.scripts]
+mdok = "mdok.cli:main"
+mda = "mdok.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/anton/mdok"
+Repository = "https://github.com/anton/mdok"
+Issues = "https://github.com/anton/mdok/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mdok-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mdok-0.1.0/src/mdok/__init__.py

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

mdok-0.1.0/src/mdok/__main__.py

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

mdok-0.1.0/src/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-0.1.0/src/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())