{"id":35640843,"url":"https://github.com/anuragkr29/md-preview-pdf","last_synced_at":"2026-01-13T21:40:06.961Z","repository":{"id":332023875,"uuid":"1127548394","full_name":"anuragkr29/md-preview-pdf","owner":"anuragkr29","description":"A state-of-the-art Markdown to PDF converter that preserves the exact visual appearance of markdown previews, including full support for Mermaid diagrams, syntax highlighting, math equations, and GitHub Flavored Markdown.","archived":false,"fork":false,"pushed_at":"2026-01-12T04:50:57.000Z","size":2787,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T09:59:52.683Z","etag":null,"topics":["automation","browser-rendering","chromium","cli-tool","dev-tools","developer-tools","headless-chrome","markdown","markdown-to-pdf","mermaid","pdf-generate","pdf-generation","vscode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/anuragkr29.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-01-04T05:32:45.000Z","updated_at":"2026-01-12T04:51:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"ebeb30b1-3d2e-4cea-bd86-3157cb12b7be","html_url":"https://github.com/anuragkr29/md-preview-pdf","commit_stats":null,"previous_names":["anuragkr29/md-preview-pdf"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/anuragkr29/md-preview-pdf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anuragkr29%2Fmd-preview-pdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anuragkr29%2Fmd-preview-pdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anuragkr29%2Fmd-preview-pdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anuragkr29%2Fmd-preview-pdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anuragkr29","download_url":"https://codeload.github.com/anuragkr29/md-preview-pdf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anuragkr29%2Fmd-preview-pdf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["automation","browser-rendering","chromium","cli-tool","dev-tools","developer-tools","headless-chrome","markdown","markdown-to-pdf","mermaid","pdf-generate","pdf-generation","vscode"],"created_at":"2026-01-05T11:17:45.689Z","updated_at":"2026-01-13T21:40:06.937Z","avatar_url":"https://github.com/anuragkr29.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MD Preview PDF 📄\n\nA state-of-the-art Markdown to PDF converter that preserves the exact visual appearance of markdown previews, including full support for Mermaid diagrams, syntax highlighting, math equations, and GitHub Flavored Markdown.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)\n[![ESLint](https://img.shields.io/badge/ESLint-9.0-brightgreen)](https://eslint.org/)\n![Tests](https://img.shields.io/badge/Tests-26%20passing-brightgreen)\n\n## ✨ Features\n\n- **Full Markdown Support**: Complete GFM (GitHub Flavored Markdown) support\n- **Mermaid Diagrams**: Flowcharts, sequence diagrams, class diagrams, and more\n- **Syntax Highlighting**: 150+ programming languages with beautiful themes\n- **Math Equations**: LaTeX math rendering via KaTeX\n- **Multiple Themes**: GitHub (light/dark), VS Code (light/dark)\n- **Table of Contents**: Auto-generated TOC with customizable depth\n- **Task Lists**: Checkbox support for TODO lists\n- **Footnotes**: Full footnote support\n- **Custom Containers**: Tips, warnings, info boxes, and more\n- **Emoji Support**: Convert `:emoji:` shortcodes to unicode\n- **High-Fidelity Output**: Uses Puppeteer for pixel-perfect PDF generation\n\n### What's new in v1.1.0\n- Render YAML front matter as an HTML table in generated PDFs for clearer metadata presentation\n- Comprehensive security hardening (SRI for CDNs, improved escaping, stricter Mermaid security level)\n- Refactored CSS rendering into dedicated modules for improved maintainability\n\n## 📦 Installation\n\n### From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/anuragkr29/md-preview-pdf.git\ncd md-preview-pdf\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Link for global CLI usage (optional)\nnpm link\n```\n\n### From NPM\n\n```bash\n# Global installation\nnpm install -g md-preview-pdf\n\n# Local installation\nnpm install md-preview-pdf\n```\n\n## 🚀 Quick Start\n\n### Command Line\n\n```bash\n# Basic conversion\nmd-preview-pdf document.md\n\n# Specify output file\nmd-preview-pdf document.md output.pdf\n\n# Use dark theme\nmd-preview-pdf document.md --theme github-dark\n\n# Add page numbers\nmd-preview-pdf document.md --page-numbers\n\n# Generate table of contents\nmd-preview-pdf document.md --toc\n\n# TOC with custom depth\nmd-preview-pdf document.md --toc --toc-depth 2\n```\n\n\u003e **Note**: Table of contents generation requires a `${toc}` marker in your markdown file where you want the TOC to appear. Example:\n\u003e ```markdown\n\u003e # My Document\n\u003e \n\u003e ${toc}\n\u003e \n\u003e ## Section 1\n\u003e Content here...\n\u003e ```\n\n### Programmatic Usage\n\n```typescript\nimport { Converter, convert } from 'md-preview-pdf';\n\n// Quick convert\nconst result = await convert('document.md', 'output.pdf', {\n  theme: { name: 'github' },\n  pdf: { format: 'A4' },\n});\n\n// Using the Converter class\nconst converter = new Converter({\n  theme: { name: 'github-dark' },\n  toc: true,\n  math: true,\n});\n\nconst result = await converter.convertFile('input.md', 'output.pdf');\nconsole.log(`PDF generated: ${result.outputPath}`);\n\n// Don't forget to cleanup\nawait converter.cleanup();\n```\n\n## 📋 CLI Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-t, --theme \u003ctheme\u003e` | Theme (github, github-dark, vscode-light, vscode-dark) | `github` |\n| `-f, --format \u003cformat\u003e` | Page format (A4, A3, A5, Letter, Legal, Tabloid) | `A4` |\n| `--landscape` | Use landscape orientation | `false` |\n| `--no-background` | Disable background printing | `true` |\n| `-m, --margin \u003cmargin\u003e` | Page margins (e.g., \"20mm\" or \"10mm,15mm,20mm,15mm\") | `20mm` |\n| `--toc` | Generate table of contents | `false` |\n| `--toc-depth \u003cdepth\u003e` | TOC heading depth (1-6) | `3` |\n| `--html` | Also output HTML file | `false` |\n| `--no-math` | Disable KaTeX math rendering | `true` |\n| `--no-emoji` | Disable emoji conversion | `true` |\n| `--no-highlight` | Disable syntax highlighting | `true` |\n| `--mermaid-theme \u003ctheme\u003e` | Mermaid theme (default, forest, dark, neutral, base) | `default` |\n| `--header \u003ctemplate\u003e` | Custom header HTML template | - |\n| `--footer \u003ctemplate\u003e` | Custom footer HTML template | - |\n| `--page-numbers` | Add page numbers to footer | `false` |\n| `--css \u003cpath\u003e` | Custom CSS file path | - |\n| `--debug` | Run in debug mode (show browser) | `false` |\n| `-v, --verbose` | Verbose output | `false` |\n| `-q, --quiet` | Quiet mode | `false` |\n\n## 🎨 Themes\n\nList available themes:\n\n```bash\nmd-preview-pdf themes\n```\n\n### Available Themes\n\n- **github**: GitHub light theme (default)\n- **github-dark**: GitHub dark theme\n- **vscode-light**: VS Code light theme\n- **vscode-dark**: VS Code dark theme\n\n### Customizing Theme Styling\n\nThemes use a modular architecture with separate color palettes and CSS styling:\n\n**Structure:**\n- Color palettes: `src/themes/colors/*.ts` (defines CSS variables)\n- Theme CSS: `src/themes/*.ts` (imports colors and applies styling)\n\n**Available Themes:**\n\n1. **GitHub Light Theme**\n   - Colors: [src/themes/colors/github-colors.ts](src/themes/colors/github-colors.ts)\n   - CSS: [src/themes/github.ts](src/themes/github.ts)\n   - Primary colors: `--bgColor-default: #ffffff`, `--fgColor-default: #1f2328`\n\n2. **GitHub Dark Theme**\n   - Colors: [src/themes/colors/github-dark-colors.ts](src/themes/colors/github-dark-colors.ts)\n   - CSS: [src/themes/github-dark.ts](src/themes/github-dark.ts)\n   - Primary colors: `--bgColor-default: #0d1117`, `--fgColor-default: #e6edf3`\n\n3. **VS Code Light Theme**\n   - Colors: [src/themes/colors/vscode-light-colors.ts](src/themes/colors/vscode-light-colors.ts)\n   - CSS: [src/themes/vscode-light.ts](src/themes/vscode-light.ts)\n   - Primary colors: `--bgColor-default: #ffffff`, `--fgColor-default: #333333`\n\n4. **VS Code Dark Theme**\n   - Colors: [src/themes/colors/vscode-dark-colors.ts](src/themes/colors/vscode-dark-colors.ts)\n   - CSS: [src/themes/vscode-dark.ts](src/themes/vscode-dark.ts)\n   - Primary colors: `--bgColor-default: #1e1e1e`, `--fgColor-default: #d4d4d4`\n\n**To customize a theme:**\n\n1. Edit color values in the appropriate `colors/*.ts` file (uses CSS custom properties)\n2. Modify styling rules in the theme's main `.ts` file if needed\n3. Rebuild and test:\n\n```bash\nnpm run build\nmd-preview-pdf tests/samples/simple-test.md output.pdf --theme github-dark\n```\n\nThis modular approach separates color definitions from styling logic, making themes easier to maintain and extend.\n\n### Sample Output\n\nThe following PDFs demonstrate the output quality across all themes:\n\n| Theme | Simple Test | File Size |\n|-------|-------------|-----------|\n| [GitHub Light](tests/output/examples/simple-github.pdf) | [View](tests/output/examples/simple-github.pdf) | 130 KB |\n| [GitHub Dark](tests/output/examples/simple-github-dark.pdf) | [View](tests/output/examples/simple-github-dark.pdf) | 130 KB |\n| [VS Code Light](tests/output/examples/simple-vscode-light.pdf) | [View](tests/output/examples/simple-vscode-light.pdf) | 134 KB |\n| [VS Code Dark](tests/output/examples/simple-vscode-dark.pdf) | [View](tests/output/examples/simple-vscode-dark.pdf) | 134 KB |\n\n## 📊 Supported Mermaid Diagrams\n\n\n```mermaid\nflowchart TD\n    A[Start] --\u003e B{Decision}\n    B --\u003e|Yes| C[OK]\n    B --\u003e|No| D[End]\n```\n\n\nSupported diagram types:\n- Flowcharts\n- Sequence diagrams\n- Class diagrams\n- State diagrams\n- Entity Relationship diagrams\n- Gantt charts (full-width rendering)\n- Pie charts\n- Git graphs\n- User Journey diagrams\n\n### Mermaid Themes and Configuration\n\nThe converter automatically selects the appropriate Mermaid theme based on your document theme:\n\n| Document Theme | Mermaid Theme |\n|---|---|\n| `github` | `default` |\n| `github-dark` | `dark` |\n| `vscode-light` | `default` |\n| `vscode-dark` | `dark` |\n\nYou can also explicitly set the Mermaid theme via CLI:\n\n```bash\n# Use forest theme\nmd-preview-pdf document.md --mermaid-theme forest\n\n# Use neutral theme\nmd-preview-pdf document.md --mermaid-theme neutral\n```\n\n**Available Mermaid themes**: `default`, `forest`, `dark`, `neutral`, `base`\n\n\u003e **Note**: Invalid theme names will trigger a warning and fallback to the `default` theme automatically.\n\n\n## ➗ Math Equations\n\nInline math with single dollar signs:\n\n```markdown\nThe formula $E = mc^2$ is famous.\n```\n\nBlock math with double dollar signs:\n\n```markdown\n$$\n\\int_{a}^{b} f(x) \\, dx = F(b) - F(a)\n$$\n```\n\n## 📝 Front Matter\n\nUse YAML front matter to configure document-specific options:\n\n```yaml\n---\ntitle: \"My Document\"\nauthor: \"John Doe\"\ndate: \"2024-01-01\"\npdfs:\n  format: Letter\n  margin:\n    top: \"25mm\"\n    bottom: \"25mm\"\n---\n```\n\nIn v1.1.0 the YAML front matter is also rendered as an HTML table in the generated PDF, providing a clear metadata summary at the top of the document.\n\n## 📁 Custom Containers\n\n```markdown\n::: tip Pro Tip\nThis is a helpful tip!\n:::\n\n::: warning Warning\nBe careful about this!\n:::\n\n::: danger Danger\nThis is critical!\n:::\n\n::: info Information\nHere's some additional info.\n:::\n\n::: details Click to expand\nHidden content here...\n:::\n```\n\n## 🛠️ Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Run in development mode\nnpm run dev -- input.md\n\n# Lint code\nnpm run lint\n```\n\n## 🔧 API Reference\n\n### Converter Class\n\n```typescript\nclass Converter {\n  constructor(options?: ConverterOptions);\n  \n  // Convert markdown file to PDF\n  convertFile(input: string, output?: string): Promise\u003cConversionResult\u003e;\n  \n  // Convert markdown string to PDF buffer\n  convertString(markdown: string, basePath?: string): Promise\u003cBuffer\u003e;\n  \n  // Convert multiple files\n  convertFiles(inputs: string[], outputDir?: string): Promise\u003cConversionResult[]\u003e;\n  \n  // Generate HTML from markdown\n  generateHtml(markdown: string, basePath?: string): Promise\u003cstring\u003e;\n  \n  // Parse markdown without rendering\n  parseMarkdown(markdown: string): ParsedMarkdown;\n  \n  // Update options\n  setOptions(options: Partial\u003cConverterOptions\u003e): void;\n  \n  // Get current options\n  getOptions(): ConverterOptions;\n  \n  // Clean up resources\n  cleanup(): Promise\u003cvoid\u003e;\n}\n```\n\n### ConverterOptions\n\n```typescript\ninterface ConverterOptions {\n  pdf?: PDFOptions;           // PDF generation options\n  theme?: ThemeOptions;       // Theme configuration\n  mermaid?: MermaidOptions;   // Mermaid diagram options\n  toc?: boolean;              // Enable table of contents\n  tocDepth?: number;          // TOC depth (1-6)\n  outputHtml?: boolean;       // Also output HTML\n  math?: boolean;             // Enable KaTeX math\n  emoji?: boolean;            // Enable emoji conversion\n  highlight?: boolean;        // Enable syntax highlighting\n  basePath?: string;          // Base path for relative resources\n  debug?: boolean;            // Debug mode\n}\n```\n## 💻 System Requirements\n\n### Minimum Requirements\n- **Node.js**: \u003e= 18.0.0\n- **npm**: \u003e= 8.0.0\n- **Memory**: 512MB minimum (1GB+ recommended for large documents)\n\n### Operating System Compatibility\n\n#### macOS\n- **Minimum**: macOS 11 (Big Sur) or later\n- **Why**: Bundled Chromium requires macOS 11+\n- **Older Macs**: For macOS 10.x, install Google Chrome manually and the tool will automatically use it\n\n#### Windows\n- **Minimum**: Windows 10 (version 1809) or later\n- **Why**: Bundled Chromium requires Windows 10 1809+\n- **Older Windows**: Install Google Chrome manually for compatibility\n\n#### Linux\n- **Most distributions supported** (Ubuntu 18.04+, Debian 10+, Fedora 32+, etc.)\n- Required system packages may vary by distribution\n- See [Puppeteer system requirements](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md) for details\n\n### Browser Requirements\n\nThis tool uses Puppeteer which automatically downloads Chromium. However, if the bundled Chromium is incompatible with your system:\n\n1. **Install Google Chrome** (recommended): The tool will automatically detect and use it\n2. **Set custom Chrome path**:\n   ```bash\n   export PUPPETEER_EXECUTABLE_PATH=\"/path/to/chrome\"\n   ```\n\n## 🔧 Troubleshooting\n\n### \"dyld: cannot load 'Google Chrome for Testing'\" (macOS)\n\n**Problem**: This error occurs on macOS 10.x (Catalina and older) because the bundled Chromium requires macOS 11+.\n\n**Solution**:\n1. Install [Google Chrome](https://www.google.com/chrome/) from the official website\n2. The tool will automatically detect and use your system Chrome installation\n3. Alternatively, set the Chrome path manually:\n   ```bash\n   export PUPPETEER_EXECUTABLE_PATH=\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\"\n   md-preview-pdf document.md\n   ```\n\n### \"Failed to launch the browser process\" (Windows)\n\n**Problem**: Bundled Chromium incompatible with older Windows versions.\n\n**Solution**:\n1. Install [Google Chrome](https://www.google.com/chrome/)\n2. Or set Chrome path:\n   ```bash\n   set PUPPETEER_EXECUTABLE_PATH=\"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\"\n   md-preview-pdf document.md\n   ```\n\n### Out of Memory Errors\n\n**Problem**: Large documents exhaust available memory.\n\n**Solution**:\n1. Increase Node.js memory limit:\n   ```bash\n   export NODE_OPTIONS=\"--max-old-space-size=4096\"\n   md-preview-pdf large-document.md\n   ```\n2. Split large documents into smaller files\n3. Disable resource-intensive features:\n   ```bash\n   md-preview-pdf document.md --no-highlight --no-math\n   ```\n\n### Slow Performance\n\n**Tips**:\n- First conversion is slower (Chromium downloads)\n- Use `--no-mermaid` if you don't have diagrams\n- Disable unused features (`--no-math`, `--no-emoji`, `--no-highlight`)\n- Consider SSD for faster file I/O\n\n### Getting Help\n\n1. Check [Puppeteer troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md)\n2. Search [existing issues](https://github.com/anuragkr29/md-preview-pdf/issues)\n3. Create a [new issue](https://github.com/anuragkr29/md-preview-pdf/issues/new) with:\n   - Operating system and version\n   - Node.js version (`node --version`)\n   - Full error message\n   - Command that failed\n\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm test -- --coverage\n\n# Run tests in watch mode\nnpm test -- --watch\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 🙏 Acknowledgments\n\n- [markdown-it](https://github.com/markdown-it/markdown-it) - Markdown parser\n- [Puppeteer](https://pptr.dev/) - Headless Chrome for PDF generation\n- [Mermaid](https://mermaid.js.org/) - Diagram rendering\n- [KaTeX](https://katex.org/) - Math rendering\n- [highlight.js](https://highlightjs.org/) - Syntax highlighting\n\n---\n\n**Created by [Anurag Kumar](https://github.com/anuragkr29)**\n\n**Repository**: [md-preview-pdf](https://github.com/anuragkr29/md-preview-pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanuragkr29%2Fmd-preview-pdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanuragkr29%2Fmd-preview-pdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanuragkr29%2Fmd-preview-pdf/lists"}