mdviewer 0.2.0__py3-none-any.whl

mdviewer/app.py

@@ -0,0 +1,159 @@
+import os
+
+from bs4 import BeautifulSoup
+from flask import Flask, abort, render_template, request, send_from_directory
+from livereload import Server
+from markdown_it import MarkdownIt
+
+from mdviewer.search.fd_search import search_filenames
+from mdviewer.search.rg_search import search_content
+
+BASE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+app = Flask(
+    __name__,
+    template_folder=os.path.join(BASE_DIR, "templates"),
+    static_folder=os.path.join(BASE_DIR, "static"),
+)
+md = MarkdownIt()
+MARKDOWN_ROOT = os.path.abspath(".")
+EXCLUDED_DIRS = {'.git', '.venv', '__pycache__', 'node_modules', '.ruff_cache'}
+
+
+# build_tree function to create a directory tree
+def build_tree(root_dir):
+    tree = {}
+    for dirpath, dirnames, filenames in os.walk(root_dir):
+        rel_path = os.path.relpath(dirpath, root_dir)
+
+        # Exclude unwanted directories
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDED_DIRS]
+
+        node = tree
+        if rel_path != ".":
+            for part in rel_path.split(os.sep):
+                node = node.setdefault(part, {})
+
+        for filename in filenames:
+            if filename.endswith(".md"):
+                node[filename] = os.path.relpath(
+                    os.path.join(dirpath, filename), root_dir
+                )
+    return tree
+
+
+# Flask routes
+@app.route("/")
+def index():
+    file_tree = build_tree(MARKDOWN_ROOT)
+    return render_template(
+        "index.html", tree=file_tree, initial_file=app.config.get("INITIAL_FILE")
+    )
+
+
+@app.route("/files/<path:filepath>")
+def serve_file(filepath):
+    full_path = os.path.join(MARKDOWN_ROOT, filepath)
+    if not os.path.isfile(full_path):
+        abort(404)
+    return send_from_directory(MARKDOWN_ROOT, filepath)
+
+
+@app.route("/view/<path:filename>")
+def view_markdown(filename):
+    full_path = os.path.abspath(os.path.join(MARKDOWN_ROOT, filename))
+
+    if not full_path.startswith(MARKDOWN_ROOT):
+        abort(403)
+
+    if os.path.isdir(full_path):
+        entries = []
+        for item in sorted(os.listdir(full_path)):
+            if item.startswith("."):
+                continue  # Skip hidden files
+            item_path = os.path.join(filename, item)
+            if os.path.isdir(os.path.join(MARKDOWN_ROOT, item_path)):
+                entries.append((item + "/", item_path))
+            elif item.endswith(".md"):
+                entries.append((item, item_path))
+        return render_template(
+            "viewer.html",
+            folder=filename,
+            entries=entries,
+            content=None,
+            filename=filename,
+        )
+
+    elif os.path.isfile(full_path):
+        with open(full_path, encoding="utf-8") as f:
+            content_md = f.read()
+            html = md.render(content_md)
+
+        # Fix image paths
+        soup = BeautifulSoup(html, "html.parser")
+        for img in soup.find_all("img"):
+            src = img.get("src")
+            if src and not src.startswith("http") and not src.startswith("/files/"):
+                img_path = os.path.normpath(
+                    os.path.join(os.path.dirname(filename), src)
+                )
+                img["src"] = f"/files/{img_path}"
+
+        return render_template(
+            "viewer.html", content=str(soup), entries=None, filename=filename
+        )
+
+    else:
+        abort(404)
+
+
+# Search functionality
+@app.route("/search")
+def search():
+    query = request.args.get("q", "").strip()
+    mode = request.args.get("mode", "fd")  # switch between fd or rg
+    results = []
+
+    if query:
+        if mode == "rg":
+            results = search_content(query, MARKDOWN_ROOT)
+        else:
+            results = search_filenames(query, MARKDOWN_ROOT)
+
+    return render_template("search.html", results=results, query=query, mode=mode)
+
+
+def start_server(markdown_root, open_file=None):
+    global MARKDOWN_ROOT
+    MARKDOWN_ROOT = os.path.abspath(markdown_root)
+    app.config["INITIAL_FILE"] = open_file
+
+    server = Server(app.wsgi_app)
+
+    # 🔁 Watch templates, static files, and markdown
+    server.watch("templates/**/*.html")
+    server.watch("static/**/*.js")
+    server.watch("static/**/*.css")
+    server.watch("**/*.md")
+
+    # print(f"🔄 Serving http://127.0.0.1:5000")
+    if open_file:
+        print(f"📄 Opening file: {open_file}")
+
+    server.serve(port=5000, host="127.0.0.1", debug=True)
+
+
+if __name__ == "__main__":
+    server = Server(app.wsgi_app)
+
+    # Watch all .md files starting from the project root
+    server.watch("**/*.md")
+
+    # Watch template changes
+    server.watch("templates/*.html")
+
+    # Optionally watch static JS/CSS too
+    server.watch("static/*.js")
+    # server.watch("static/*.css")
+
+    server.serve(port=5000, debug=True)

mdviewer/cli.py

@@ -0,0 +1,47 @@
+import argparse
+import os
+import webbrowser
+from mdviewer.app import start_server  # make app.py expose a `start_server(path)`
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="mdv", description="📘 mdviewer — GitHub-style Markdown viewer"
+    )
+    parser.add_argument(
+        "target", nargs="?", default="README.md", help="Markdown file or folder to view"
+    )
+    parser.add_argument(
+        "-o",
+        "--open",
+        action="store_true",
+        help="Open in browser after starting server (default: off)",
+    )
+
+    args = parser.parse_args()
+
+    # Expand ~ and resolve absolute path
+    target = os.path.abspath(os.path.expanduser(args.target))
+
+    if not os.path.exists(target):
+        print(f"❌ Error: Path not found: {target}")
+        return
+
+    # Determine root (folder) and optional file
+    root = target if os.path.isdir(target) else os.path.dirname(target)
+    open_file = target if os.path.isfile(target) else None
+
+    print(f"📂 Serving: {root}")
+
+    start_server(markdown_root=root, open_file=open_file)
+
+    print("🌐 Open in browser: http://127.0.0.1:5000")
+    print("🛑 Press Ctrl-C to stop server.")
+    print("❗ Remember to close the browser tab before restarting.")
+
+    if args.open:
+        webbrowser.open_new_tab("http://127.0.0.1:5000")
+
+
+if __name__ == "__main__":
+    main()

mdviewer/search/fd_search.py

@@ -0,0 +1,16 @@
+import subprocess
+import os
+
+
+def search_filenames(query, root):
+    try:
+        result = subprocess.run(
+            ["fd", "--type", "f", "--extension", "md", query, root],
+            capture_output=True,
+            text=True,
+        )
+        matches = result.stdout.strip().split("\n")
+        return [os.path.relpath(m, root) for m in matches if m]
+    except Exception as e:
+        print("[FD ERROR]", e)
+        return []

mdviewer/search/rg_search.py

@@ -0,0 +1,16 @@
+import subprocess
+import os
+
+
+def search_content(query, root):
+    try:
+        result = subprocess.run(
+            ["rg", "--files-with-matches", "-i", "-t", "md", query, root],
+            capture_output=True,
+            text=True,
+        )
+        matches = result.stdout.strip().split("\n")
+        return [os.path.relpath(m, root) for m in matches if m]
+    except Exception as e:
+        print("[RG ERROR]", e)
+        return []

mdviewer-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mdviewer
+Version: 0.2.0
+Summary: GitHub-style Markdown viewer
+Author-email: Biao Jiang <github@minsignal.com>
+License: MIT
+Description-Content-Type: text/markdown
+Requires-Dist: flask
+Requires-Dist: livereload
+Requires-Dist: markdown-it-py
+Requires-Dist: beautifulsoup4
+
+# 📝 Markdown Viewer (GitHub-Style)
+
+[![PyPI](https://img.shields.io/pypi/v/mdviewer.svg)](https://pypi.org/project/mdviewer)
+[![Homebrew](https://img.shields.io/badge/Homebrew-mdviewer-blue)](https://github.com/yourusername/homebrew-mdviewer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A GitHub-style Markdown viewer for local docs, with file tree, search, and live reload.
+
+A local Markdown documentation browser that:
+
+- Renders `.md` files with GitHub-flavored styles
+- Displays a recursive file/folder tree
+- Supports live plain-text filtering (client-side)
+- Supports filename/content search using `fd` or `rg`
+- Auto-reloads edited files
+- Dark/light mode toggle
+- Export/Print to PDF
+- Breadcrumb navigation with folder/file icons
+- Highlights current file in tree and auto-expands
+
+## 🚀 Installation
+
+### 🔧 Option 1: Homebrew (macOS/Linux)
+
+```bash
+brew tap biaojiang/mdviewer
+brew install mdviewer
+```
+
+### 🐍 Option 2: Python (via pip)
+
+```
+pip install mdviewer
+```
+
+**Optionally add an alias:**
+
+```bash
+echo 'alias mdv="mdviewer"' >> ~/.zshrc
+source ~/.zshrc
+# or symlink
+sudo ln -s $(which mdviewer) /usr/local/bin/mdv
+```
+
+### 🔧 Option 3: Build from Source
+
+```sh
+# Install Python deps
+pip install -r requirements.txt
+
+# Optional: use a venv
+python -m venv .venv
+source .venv/bin/activate
+
+# Install tools if needing advanced search
+brew install fd ripgrep
+# or
+sudo apt install fd-find ripgrep
+
+# ▶️ Run the Server
+python app.py
+
+Open [http://127.0.0.1:5000](http://127.0.0.1:5000/) in your browser.
+```
+
+---
+
+## 🚀 Features
+
+- ✅ GitHub-style rendering via `markdown-it-py` + GitHub CSS
+- ✅ Auto-expandable file tree using `<details>`
+- ✅ Live filtering with reset button
+- ✅ Backend-powered search:
+	- `fd`: fuzzy filename matching
+	- `rg`: content search
+- ✅ Flask-based local webserver
+- ✅ MathJax support for LaTeX
+- ✅ Reload current buffer on changes (with `livereload`)
+- ✅ Font Awesome icons for folders/files
+- ✅ Breadcrumb that reflects navigation path
+- ✅ Highlight + auto-expand tree for active file
+- ✅ PDF/Print export button with clean print CSS
+
+---
+
+## 📁 File Structure
+
+```text
+.
+├── docs
+│   └── math
+│       └── math-test.md
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+├── screenshot.png
+├── src
+│   ├── mdviewer
+│   │   ├── __init__.py
+│   │   ├── app.py
+│   │   ├── cli.py
+│   │   └── search
+├── static
+│   ├── script.js
+│   └── style.css
+└── templates
+    ├── index.html
+    ├── search.html
+    └── viewer.html
+```
+
+---
+
+## 🔍 Search Modes
+
+- `fd`: fuzzy filename match (fast)
+- `rg`: full-text content match (powerful)
+
+---
+
+## ⚙️ Keyboard & UI
+
+- 🌓 Dark/light toggle
+- ⌨️ Live tree filter with reset
+- 🗂 Expandable nested folders
+- 🔗 Click to render `.md` file in browser
+- 🖨 Export/Print to PDF button
+- 📁 Breadcrumb with Font Awesome icons
+- 📄 Highlight + expand tree for active file
+
+---
+
+## ⏭️ Next Steps
+
+-
+
+---
+
+## 📄 License
+
+MIT

mdviewer-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mdviewer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdviewer/app.py,sha256=PjUKTAH9EQVQKsOKpRWxQ4iHYv4snSn6uTUWL2k9ekM,4739
+mdviewer/cli.py,sha256=29xv4X0TNWYXRAIsXQJInojn7WSmq4NwtGukxti_OJo,1354
+mdviewer/search/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdviewer/search/fd_search.py,sha256=iIohgsG3S_z_24g6vogAAVgIwdtn8ApalDjEcMrTfrg,434
+mdviewer/search/rg_search.py,sha256=I4gwbNDLMUciOiOp4gGbkALfkD1bpU1261AuBalDEIw,438
+mdviewer-0.2.0.dist-info/METADATA,sha256=SOyRz6HhpTro48o84ZFyoHd5XHiGZyL6IrUgwZwnoFk,3447
+mdviewer-0.2.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+mdviewer-0.2.0.dist-info/entry_points.txt,sha256=U5yxbTo6maxj6cf4xTM1kxaKR406ul4m25eCZn05lzc,47
+mdviewer-0.2.0.dist-info/top_level.txt,sha256=Suu9lMIhaz8aJV0UI3_nihKY6t_fIAp2kxXxRHTZl6Q,9
+mdviewer-0.2.0.dist-info/RECORD,,

mdviewer-0.2.0.dist-info/WHEEL

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

mdviewer-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mdviewer = mdviewer.cli:main

mdviewer-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mdviewer