https://github.com/sayfalse/mintpdf
🌿 AI-Free Professional PDF Generator for the Terminal
https://github.com/sayfalse/mintpdf
cli markdown-parser offline-first pdf-generator python reportlab
Last synced: 23 days ago
JSON representation
🌿 AI-Free Professional PDF Generator for the Terminal
- Host: GitHub
- URL: https://github.com/sayfalse/mintpdf
- Owner: sayfalse
- License: mit
- Created: 2026-06-28T17:28:47.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-28T21:59:21.000Z (about 1 month ago)
- Last Synced: 2026-06-28T23:14:42.530Z (about 1 month ago)
- Topics: cli, markdown-parser, offline-first, pdf-generator, python, reportlab
- Language: Python
- Homepage: https://github.com/sayfalse/mintpdf
- Size: 109 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
🌿 Mint PDF
AI-Free Professional PDF Generator for the Terminal
[](#)
[](LICENSE)
[](#)
[](#)
A modern command-line application that parses plain text or markdown documents and compiles them into beautifully formatted, publication-ready PDF files. Works 100% locally.
---
## 🟢 Features
- **100% Offline-First**: Does not call any cloud APIs, external AI models, or require internet connectivity.
- **Rules-Based Structural Analyzer**: Scans and parses document elements (lists, tables, quotes, code blocks) to recommend optimal design combinations.
- **Case-Insensitive Input Validators**: Hardened configuration and prompt validators to resolve choice variations automatically.
- **Dynamic Themes**: Loads custom JSON color palettes from the workspace `themes/` directory.
- **Template Inheritance**: Resolves nested layout styles with recursive parent class extends (`"extends": ""`).
- **Dot-Leader Tables of Contents**: Generates multi-level, aligned document outlines.
- **Cell-Wrapping Tables**: Automatically wraps column cells in flowable paragraphs to prevent overflow off page margins.
- **Clean CLI UI**: Styled with Rich columns, panels, pre-generation check tables, and dynamic progress bars.
---
## 📦 Project Structure
```
mint-pdf/
│
├── main.py # Startup bootstrapper
├── cli.py # Console interfaces, wizard flow, and progress bars
├── config.py # Configuration controller (migrations, backup & recovery)
├── settings.py # Configuration schema definitions (Pydantic validated)
├── pdf_engine.py # Main PDF compiler & canvas composer (using ReportLab)
├── cover_page.py # Front cover layout generator
├── formatter.py # Document structure parsing (lists, tables, code blocks)
├── template_manager.py # Layout templates manager (inheritance resolver)
├── theme_manager.py # Theme palettes controller
├── font_manager.py # Font registry & safe PostScript mapping
├── document_analyzer.py # Rule-based structure analyzer
├── toc.py # Table of Contents generator
├── metadata.py # Document metadata schema
├── file_manager.py # OS-independent file IO helper
├── utils.py # Page conversions and helper utils
└── logger.py # Rotating file logs & error trace managers
```
---
## 🛠️ Installation Guide
### Prerequisites
- **Python 3.12** or newer installed.
- **pip** package manager.
### Setup Steps
1. Navigate to the project directory:
```bash
cd "mint-pdf"
```
2. Install the required dependencies:
```bash
pip install -r requirements.txt
```
3. Boot the application:
```bash
python main.py
```
---
## 📖 Usage Wizard Flow
1. **Setup Output**: On startup, configure your default PDF export directory.
2. **Accept Text**: Paste text block directly or load files (`.txt`, `.md`, `.docx`).
3. **Analyze**: The engine runs parsing diagnostics and recommends themes and layout configurations.
4. **Style Select**: Confirm template layout (Standard, Executive, Thesis) and visual theme (Professional, Forest, Ocean).
5. **Metadata**: Enter Title, Author, and Subject properties (injected into the native PDF headers).
6. **Compile**: A multi-stage Rich progress bar tracks generation and handles file name collisions.
---
## ⚙️ Configuration Schema
Active settings are saved in `config.json` and validated via Pydantic:
- `config_version`: Migrations tracking schema version.
- `output_dir`: Path to save compiled PDF files.
- `theme`: Primary default visual palette (e.g. `Professional`, `Forest`).
- `default_font`: Typography family (e.g. `Helvetica`, `Times New Roman`, `Inter`).
- `page_size`: Standard page sizes (`LETTER`, `A4`, `LEGAL`).
- `margins`: Top, bottom, left, right margins in points.
- `auto_toc`: Automatically generate document tables of contents.
- `auto_page_numbers`: Dynamic page numbering printed on canvas footers.
---
## 🎨 Theme & Template Customs
### Custom JSON Themes
Add custom color schemes by dropping `.json` files in the `themes/` directory:
```json
{
"name": "Mint Green",
"primary": "#38A169",
"secondary": "#2F855A",
"accent": "#48BB78",
"text": "#2D3748",
"bg": "#FFFFFF",
"border": "#E2E8F0",
"table_row_alt": "#F0FFF4",
"link_color": "#38A169"
}
```
### Custom Templates (Inheritance)
Drop custom template layouts in `templates/` using `"extends"` to inherit properties:
```json
{
"name": "Leaflet",
"extends": "Standard",
"category": "Compact",
"description": "Slimmer layout margins",
"margins": {
"left": 36.0,
"right": 36.0
}
}
```
---
## 🤝 Contribution Guidelines
1. **PEP 8**: Follow Python PEP 8 formatting rules. Add type hints and detailed docstrings to all new methods.
2. **Error Safety**: Mask console output stack trace warnings. Always call `logger.log_exception` to preserve complete debug logs inside `logs/mint_pdf.log`.
3. **Immutability**: Avoid mutating state configs. Always instantiate and return updated schema copies.