A modern, JavaScript-powered Markdown to PDF converter with advanced features including Mermaid diagram support, syntax highlighting, and professional styling.
- Markdown to PDF Conversion: Convert any Markdown file to professionally formatted PDF
- JavaScript-Based Processing: Uses modern web technologies for accurate rendering
- Chrome Headless Integration: Leverages Chrome's rendering engine for high-quality output
- Cross-Platform Support: Works on macOS, Linux, and Windows
- GitHub Markdown Styling: Uses GitHub's official CSS for authentic documentation appearance
- Syntax Highlighting: Powered by Prism.js with support for 200+ programming languages
- Mermaid Diagram Support: Renders complex diagrams, flowcharts, and sequence diagrams
- Badge Rendering: Properly displays GitHub-style badges and shields
- Image Optimization: Automatically handles and optimizes images for PDF output
- Template-Based Architecture: Uses customizable HTML templates for consistent output
- Asset Management: Automatically copies referenced images and files
- JavaScript Escaping: Robust handling of special characters and Unicode content
- Error Handling: Comprehensive error reporting and graceful failure handling
- Temporary File Management: Clean workspace management with automatic cleanup
- Professional Layout: Clean, readable formatting optimized for documentation
- Print Optimization: Specialized CSS for high-quality PDF generation
- Responsive Design: Adapts to different content types and sizes
- Typography: Uses system fonts for optimal readability across platforms
- Python 3.6+
- Chrome or Chromium browser
- Internet connection (for CDN resources)
Clone the repository:
git clone <repository-url>cd builddoc
Install dependencies:
pip install -r requirements.txt
Install Chrome/Chromium (if not already installed):
macOS:
brew install --cask google-chrome # OR brew install chromiumUbuntu/Debian:
sudo apt-get install google-chrome-stable # OR sudo apt-get install chromium-browser
Convert a Markdown file to PDF:
python builddoc.py README.mdSpecify custom output file:
python builddoc.py README.md -o documentation.pdfConvert any Markdown file:
python builddoc.py path/to/your/file.mdpython builddoc.py [file] [-o OUTPUT]file: Input Markdown file (default:README.md)-o, --output: Output PDF file path (optional)
- Headers (H1-H6)
- Bold and italic text
- Lists (ordered and unordered)
- Links and images
- Code blocks and inline code
- Tables
- Blockquotes
- Horizontal rules
- Mermaid Diagrams: Use ````mermaid` code blocks for diagrams
- Syntax Highlighting: Automatic language detection for code blocks
- GitHub Flavored Markdown: Tables, strikethrough, task lists
- Badge Support: GitHub-style badges and shields
- Image Optimization: Automatic image sizing and positioning
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
sequenceDiagram
participant A as User
participant B as System
A->>B: Request
B-->>A: Response
- ModernMarkdownToPDFConverter: Main conversion class
- Template System: HTML template with embedded JavaScript
- Asset Management: File copying and reference handling
- Chrome Integration: Headless browser for PDF generation
- Input Validation: Check file existence and format
- Template Preparation: Copy template and assets to working directory
- Content Processing: Escape and embed Markdown content
- HTML Generation: Create self-contained HTML document
- PDF Conversion: Use Chrome headless for final conversion
- Cleanup: Remove temporary files and directories
- Marked.js: Markdown parsing and conversion
- Mermaid.js: Diagram rendering
- Prism.js: Syntax highlighting
- GitHub Markdown CSS: Professional styling
The template.html file can be customized to:
- Change styling and layout
- Add custom CSS
- Modify JavaScript behavior
- Include additional libraries
Key configuration variables in the template:
mermaidTheme: Mermaid diagram thememermaidWaitTime: Timeout for diagram rendering- CSS styling for different content types
For programmatic usage:
frombuilddocimportModernMarkdownToPDFConverterconverter=ModernMarkdownToPDFConverter('input.md', 'output.pdf')
converter.convert()Chrome not found:
- Ensure Chrome/Chromium is installed
- Check PATH environment variable
- Try specifying full path to Chrome executable
Missing dependencies:
pip install -r requirements.txtPermission errors:
- Ensure write permissions in output directory
- Check file system permissions
Large files:
- Increase Chrome timeout settings
- Consider breaking large documents into sections
Enable verbose output by modifying the script to add debug prints or use:
python -u builddoc.py input.md 2>&1| tee debug.log- Python 3.6 or higher
- Chrome or Chromium browser
- 100MB free disk space (for temporary files)
- Internet connection (for CDN resources)
requests: HTTP requests for online services- Standard library modules:
argparse,os,re,subprocess,sys,tempfile,shutil,pathlib
- Chrome 80+ or Chromium 80+
- Headless mode support
- PDF generation capabilities
git clone <repository-url>cd builddoc
pip install -r requirements.txt
# Make your changes
python builddoc.py test.md- GitHub: For the excellent Markdown CSS styling
- Mermaid.js: For powerful diagram rendering capabilities
- Prism.js: For comprehensive syntax highlighting
- Marked.js: For robust Markdown parsing
- Chrome Team: For the excellent headless browser capabilities