{"id":51502733,"url":"https://github.com/sayfalse/mintpdf","last_synced_at":"2026-07-07T21:01:38.610Z","repository":{"id":368062951,"uuid":"1283226650","full_name":"sayfalse/mintpdf","owner":"sayfalse","description":"🌿 AI-Free Professional PDF Generator for the Terminal","archived":false,"fork":false,"pushed_at":"2026-06-28T21:59:21.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T23:14:42.530Z","etag":null,"topics":["cli","markdown-parser","offline-first","pdf-generator","python","reportlab"],"latest_commit_sha":null,"homepage":"https://github.com/sayfalse/mintpdf","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sayfalse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-28T17:28:47.000Z","updated_at":"2026-06-28T21:59:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sayfalse/mintpdf","commit_stats":null,"previous_names":["sayfalse/mintpdf"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sayfalse/mintpdf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayfalse%2Fmintpdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayfalse%2Fmintpdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayfalse%2Fmintpdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayfalse%2Fmintpdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sayfalse","download_url":"https://codeload.github.com/sayfalse/mintpdf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sayfalse%2Fmintpdf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35242497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","markdown-parser","offline-first","pdf-generator","python","reportlab"],"created_at":"2026-07-07T21:01:37.751Z","updated_at":"2026-07-07T21:01:38.603Z","avatar_url":"https://github.com/sayfalse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cbr /\u003e\n  \u003ch1\u003e🌿 Mint PDF\u003c/h1\u003e\n  \u003cp\u003e\u003cb\u003eAI-Free Professional PDF Generator for the Terminal\u003c/b\u003e\u003c/p\u003e\n\n  [![Version](https://img.shields.io/badge/version-1.0.0-48BB78.svg?style=flat-square)](#)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-48BB78.svg?style=flat-square)](LICENSE)\n  [![Platform](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-48BB78.svg?style=flat-square)](#)\n  [![Offline First](https://img.shields.io/badge/offline-100%25-38A169.svg?style=flat-square)](#)\n\n  \u003cp\u003e\u003ci\u003eA modern command-line application that parses plain text or markdown documents and compiles them into beautifully formatted, publication-ready PDF files. Works 100% locally.\u003c/i\u003e\u003c/p\u003e\n  \n  ---\n\u003c/div\u003e\n\n## 🟢 Features\n- **100% Offline-First**: Does not call any cloud APIs, external AI models, or require internet connectivity.\n- **Rules-Based Structural Analyzer**: Scans and parses document elements (lists, tables, quotes, code blocks) to recommend optimal design combinations.\n- **Case-Insensitive Input Validators**: Hardened configuration and prompt validators to resolve choice variations automatically.\n- **Dynamic Themes**: Loads custom JSON color palettes from the workspace `themes/` directory.\n- **Template Inheritance**: Resolves nested layout styles with recursive parent class extends (`\"extends\": \"\u003cParentTemplate\u003e\"`).\n- **Dot-Leader Tables of Contents**: Generates multi-level, aligned document outlines.\n- **Cell-Wrapping Tables**: Automatically wraps column cells in flowable paragraphs to prevent overflow off page margins.\n- **Clean CLI UI**: Styled with Rich columns, panels, pre-generation check tables, and dynamic progress bars.\n\n---\n\n## 📦 Project Structure\n```\nmint-pdf/\n│\n├── main.py               # Startup bootstrapper\n├── cli.py                # Console interfaces, wizard flow, and progress bars\n├── config.py             # Configuration controller (migrations, backup \u0026 recovery)\n├── settings.py           # Configuration schema definitions (Pydantic validated)\n├── pdf_engine.py         # Main PDF compiler \u0026 canvas composer (using ReportLab)\n├── cover_page.py         # Front cover layout generator\n├── formatter.py          # Document structure parsing (lists, tables, code blocks)\n├── template_manager.py   # Layout templates manager (inheritance resolver)\n├── theme_manager.py      # Theme palettes controller\n├── font_manager.py       # Font registry \u0026 safe PostScript mapping\n├── document_analyzer.py  # Rule-based structure analyzer\n├── toc.py                # Table of Contents generator\n├── metadata.py           # Document metadata schema\n├── file_manager.py       # OS-independent file IO helper\n├── utils.py              # Page conversions and helper utils\n└── logger.py             # Rotating file logs \u0026 error trace managers\n```\n\n---\n\n## 🛠️ Installation Guide\n\n### Prerequisites\n- **Python 3.12** or newer installed.\n- **pip** package manager.\n\n### Setup Steps\n1. Navigate to the project directory:\n   ```bash\n   cd \"mint-pdf\"\n   ```\n2. Install the required dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n3. Boot the application:\n   ```bash\n   python main.py\n   ```\n\n---\n\n## 📖 Usage Wizard Flow\n\n1. **Setup Output**: On startup, configure your default PDF export directory.\n2. **Accept Text**: Paste text block directly or load files (`.txt`, `.md`, `.docx`).\n3. **Analyze**: The engine runs parsing diagnostics and recommends themes and layout configurations.\n4. **Style Select**: Confirm template layout (Standard, Executive, Thesis) and visual theme (Professional, Forest, Ocean).\n5. **Metadata**: Enter Title, Author, and Subject properties (injected into the native PDF headers).\n6. **Compile**: A multi-stage Rich progress bar tracks generation and handles file name collisions.\n\n---\n\n## ⚙️ Configuration Schema\nActive settings are saved in `config.json` and validated via Pydantic:\n- `config_version`: Migrations tracking schema version.\n- `output_dir`: Path to save compiled PDF files.\n- `theme`: Primary default visual palette (e.g. `Professional`, `Forest`).\n- `default_font`: Typography family (e.g. `Helvetica`, `Times New Roman`, `Inter`).\n- `page_size`: Standard page sizes (`LETTER`, `A4`, `LEGAL`).\n- `margins`: Top, bottom, left, right margins in points.\n- `auto_toc`: Automatically generate document tables of contents.\n- `auto_page_numbers`: Dynamic page numbering printed on canvas footers.\n\n---\n\n## 🎨 Theme \u0026 Template Customs\n\n### Custom JSON Themes\nAdd custom color schemes by dropping `.json` files in the `themes/` directory:\n```json\n{\n  \"name\": \"Mint Green\",\n  \"primary\": \"#38A169\",\n  \"secondary\": \"#2F855A\",\n  \"accent\": \"#48BB78\",\n  \"text\": \"#2D3748\",\n  \"bg\": \"#FFFFFF\",\n  \"border\": \"#E2E8F0\",\n  \"table_row_alt\": \"#F0FFF4\",\n  \"link_color\": \"#38A169\"\n}\n```\n\n### Custom Templates (Inheritance)\nDrop custom template layouts in `templates/` using `\"extends\"` to inherit properties:\n```json\n{\n  \"name\": \"Leaflet\",\n  \"extends\": \"Standard\",\n  \"category\": \"Compact\",\n  \"description\": \"Slimmer layout margins\",\n  \"margins\": {\n    \"left\": 36.0,\n    \"right\": 36.0\n  }\n}\n```\n\n---\n\n## 🤝 Contribution Guidelines\n1. **PEP 8**: Follow Python PEP 8 formatting rules. Add type hints and detailed docstrings to all new methods.\n2. **Error Safety**: Mask console output stack trace warnings. Always call `logger.log_exception` to preserve complete debug logs inside `logs/mint_pdf.log`.\n3. **Immutability**: Avoid mutating state configs. Always instantiate and return updated schema copies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayfalse%2Fmintpdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsayfalse%2Fmintpdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayfalse%2Fmintpdf/lists"}