Skillget

markdown-reader

agent
Guvenlik Denetimi
Gecti
Health Gecti
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 14 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested
Purpose
This application is a feature-rich, cross-platform Markdown editor equipped with tabbed editing, a dockable AI chat assistant, real-time preview, and dual PDF conversion modes. It is built using Python and Tkinter.

Security Assessment
The overall risk is rated as Medium. The automated code scan checked 12 files and found no dangerous patterns, no hardcoded secrets, and no requirement for dangerous system permissions. However, by design, the software makes external network requests to third-party AI providers (OpenRouter, OpenAI, and Anthropic) to power its chat and translation features. While the tool itself does not read local sensitive data or execute arbitrary shell commands, users must be aware that any text inputted into the AI chat or translation features will be transmitted over the internet. The security of that data ultimately depends on the user's own API key handling and the privacy policies of the configured AI providers.

Quality Assessment
The project is under active development, with its most recent push occurring just today. It is properly licensed under the permissive and standard MIT license, which is excellent for open-source adoption. However, community trust is currently minimal, as it has only accumulated 14 GitHub stars. Additionally, the repository lacks an available README file, which negatively impacts usability, transparency, and overall project polish.

Verdict
Use with caution: the code is safe from local exploits, but you must trust the external AI providers with your data and should supply your own API keys securely.
SUMMARY

Cross-platform Markdown editor with tabbed editing, real-time preview, AI-powered translation (OpenRouter/OpenAI/Anthropic), dockable AI chat with audit trail, automation templates, advanced table editor, dual PDF conversion modes, dark mode, and smart provider failover—built with Python and Tkinter.

README.md

Markdown Reader

Markdown Reader is a clean and intuitive Markdown editor/reader with real-time preview support and dark mode toggle. It is compatible with macOS and Windows desktop environments and built with pure Python and Tkinter.

Features

  • Tabbed Markdown editing with real-time HTML preview.
  • AI-Powered Translation: Translate Markdown documents while preserving formatting (supports OpenAI Compatible, OpenRouter, OpenAI, and Anthropic).
  • Built-in AI Agent Chat: A dockable in-app chat panel can read current document context and suggest/apply edits.
  • AI Task Automation Templates: Run reusable templates for formatting, TOC generation, summaries, and code-block cleanup.
  • Approval/Reject Workflow: Every AI-proposed change can be explicitly applied or rejected from the panel.
  • AI Audit Trail: Proposed/applied/rejected/undone AI actions are logged for auditing and rollback tracking.
  • API Key Management: Missing or rejected provider keys trigger an in-app dialog, and keys are saved in the OS credential store.
  • Progressive Translation Rendering: Long translations are split into smaller chunks, inserted into the editor as they complete, auto-scrolled into view, and tracked with a progress bar.
  • Dark mode toggle.
  • Advanced Table Editor: Interactive table insertion with customizable rows and columns.
  • Dual PDF Conversion: Fast PyMuPDF mode or advanced Docling mode for complex documents.
  • Built with pure Python, Tkinter, and ttkbootstrap — cross-platform.
  • Can be bundled as a macOS app using py2app.
  • Opens preview automatically and avoids multiple browser tabs for a smoother experience.
  • Multi-provider AI failover: Automatically switches to fallback providers on rate-limit/auth/server errors.

Editor Overview

Image

Preview Overview

Image

Installation & Usage

1. Clone the repository

git clone https://github.com/petertzy/markdown-reader.git
cd markdown-reader

2. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # macOS/Linux
# .\venv\Scripts\activate  # Windows (cmd/powershell)

3. Install dependencies

For Mac users, you should first complete the preparation steps described in the PrepareForMacUser file.

For Windows users, WeasyPrint requires additional system libraries. Complete the preparation steps described in the PrepareForWindowsUser file before installing dependencies.

With uv (recommended):

uv sync

Or with pip:

pip install .

Running the Application

python app.py

How to Use

  • Open File: Choose .md, .markdown, .html, .htm, or .pdf from the "File → Open File" menu.
  • Open with Double-Click: Double-clicking a .md file opens it directly with the app and displays the document with a real-time preview.
  • Editor-Only Mode: To open a .md file in the editor without automatically generating a web preview, configure the double-click behavior via "Settings → Open Behavior → Editor Only".
  • Dark Mode: Toggle via "View → Toggle Dark Mode".
  • Preview: Automatically opens in your web browser, only one tab is opened per session.
  • AI Translation:
    • Translate selected text: "Edit → Translate with AI → Translate Selected Text with AI"
    • Translate full document: "Edit → Translate with AI → Translate Full Document with AI"
    • Select source and target languages from dropdown menus
    • Configure provider/model/API keys: "Settings → AI Provider & API Keys..."
    • If a key is missing or rejected, the app prompts for the correct provider key and stores it in the OS credential store
    • Large translations appear progressively in the editor with automatic scrolling and a visible progress bar
  • AI Agent Chat Panel:
    • Show/hide: "View → Show AI Agent Panel"
    • You can type natural-language requests directly in the chat box; no special command syntax is required
    • The AI agent can automatically prepare edit suggestions for tasks such as summaries, formatting, TOC generation, and code-block fixes
    • Typical chat requests:
      • generate summary
      • generate table of contents
      • format this section
      • format code blocks and correct syntax
    • Supports commands like "format this section", "generate summary", and "generate table of contents"
    • Built-in automation templates can trigger repetitive editor tasks quickly
    • Can format and fix Markdown code blocks (including unclosed fences)
    • Context scope toggle: "Full document" or "Selection only"
    • Uses current document and/or selected text as context based on the selected scope
    • Workflow: send a natural-language request -> review AI preview -> click "Apply Suggestion" to apply
    • AI suggestions can be applied or rejected with confirmation and validation checks
    • "Undo AI Task" allows one-click rollback of the latest applied AI change
    • "Audit Log" shows recent AI automation events for traceability
    • Chat history is stored per document and restored automatically
  • Table Insertion: Use "Table → Insert Table" to create custom tables with interactive cell editing.
  • PDF Conversion Modes:
    • Fast mode (default): Uses PyMuPDF for quick extraction
    • Advanced mode: Enable "Tools → Use Advanced PDF Conversion (Docling)" for complex documents
    • View mode info: "Tools → PDF Converter Info"

Packaging as a macOS App (Optional)

To bundle this app as a .app, use the included setup.py script:

Build the App

rm -rf build dist
python setup.py py2app

The generated app will be located in the dist/ folder. You can launch it by double-clicking. To use it like a regular app, move it to your Applications folder.

Exit the Virtual Environment

deactivate

Submit Changes to Git

git add .
git commit -m "Update"  # Replace "Update" with a meaningful commit message
git push

Technical Details

  • GUI: tkinter, ttkbootstrap
  • Markdown Engine: markdown2
  • HTML Preview: Dynamically generated HTML opened in the default browser
  • File Conversion: html2text for HTML, PyMuPDF and docling for PDF import (pypdf is used as a fallback when PyMuPDF is unavailable)
  • PDF Export: weasyprint
  • AI Translation: requests for API communication with OpenAI Compatible, OpenRouter, OpenAI, and Anthropic
  • Configuration: Per-user settings JSON for provider/model (macOS ~/Library/Application Support/MarkdownReader/settings.json; Windows %APPDATA%/MarkdownReader/settings.json; Linux ~/.config/markdown-reader/settings.json) plus OS credential storage for API keys (keyring)
  • Auto-failover: Automatically switches AI providers when the primary provider returns rate-limit/auth/server errors

System Requirements:

Python >= 3.10

AI-powered translation:

To enable AI-powered translation features, you need to set up API keys:

  1. Open Settings -> AI Provider & API Keys....
  2. Choose provider and model.
  3. Enter API key and save.
  4. If you choose OpenAI Compatible, you can also choose a Base URL option (Navidia or Groq).

The app stores provider and model in a per-user JSON file:

  • macOS: ~/Library/Application Support/MarkdownReader/settings.json
  • Windows: %APPDATA%/MarkdownReader/settings.json
  • Linux: ~/.config/markdown-reader/settings.json

How to get API keys:

API keys are saved in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service/KWallet on Linux when available).

The app will automatically switch to a fallback provider when the primary provider returns rate-limit/auth/server errors.

License

This project is licensed under the MIT License.
See the LICENSE file for the full text.

Contributing

All contributions are welcome, including:

  • Bug reports
  • Feature suggestions
  • Pull requests
  • Documentation improvements

Please see our CONTRIBUTING guide for more details on how to get started, submit changes, or report issues.

Contributors

We are grateful to all our contributors who have made this project better! Special thanks to:

Major Contributors:

All Contributors:
See CONTRIBUTORS.md for the complete list of all contributors including:

For a detailed breakdown, please visit CONTRIBUTORS.md.

Yorumlar (0)

Sonuc bulunamadi