gospelo-md2pdf

Convert Markdown to PDF with Japanese support and MermaidJS diagrams.

Features

• Japanese Text Support: Full support for Japanese fonts (Noto Sans CJK JP, Hiragino Sans, Yu Gothic)
• MermaidJS Diagrams: Automatically renders Mermaid diagrams as PNG images via Kroki API
• Image Embedding: Automatically embeds local and remote images as Base64 data URIs for portable PDFs
• Custom CSS: Use your own stylesheets or the built-in professional style
• Markdown Extensions: Tables, fenced code blocks, TOC, metadata, and more
• Special HTML Classes: Summary boxes, warnings, pros/cons sections, page breaks
• Agent Skills: Built-in support for AI coding assistants (Claude Code, Web Claude, VS Code Copilot)

Installation

pip install gospelo-md2pdf

System Dependencies

WeasyPrint requires system libraries. Install them first:

macOS:

brew install pango glib gdk-pixbuf libffi

Ubuntu/Debian:

sudo apt install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0

Japanese Fonts (Recommended)

For Japanese text rendering:

macOS:

brew install font-noto-sans-cjk-jp

Ubuntu/Debian:

sudo apt install fonts-noto-cjk

MermaidJS Support

Mermaid diagrams are rendered using the Kroki API (no local installation required). Supported Mermaid version depends on Kroki's implementation (currently Mermaid v11.x).

For Web Claude: Add kroki.io to allowed domains:

1. Settings (gear icon) → Capabilities
2. Find "Additional allowed domains"
3. Add kroki.io

Quick Start

# Basic usage
gospelo-md2pdf report.md

# Specify output file
gospelo-md2pdf report.md output.pdf

# Specify output directory
gospelo-md2pdf report.md -o ./pdf

# Use custom CSS
gospelo-md2pdf report.md --css custom-style.css

# Keep intermediate files for debugging
gospelo-md2pdf report.md --debug

Usage

gospelo-md2pdf <input.md> [output.pdf] [options]

Arguments:
  input.md              Input Markdown file
  output.pdf            Output PDF file (optional)

Options:
  -o, --output-dir DIR  Output directory (default: current directory)
  -c, --css FILE        Custom CSS file
  --debug               Keep intermediate files (HTML, mermaid) in tmp/ directory
  --lang LANG           HTML lang attribute (default: ja)
  -q, --quiet           Suppress output messages
  --verbose             Print verbose output
  -v, --version         Show version
  -h, --help            Show help

Environment Variables

Note: --output-dir option takes precedence over the environment variable.

Markdown Features

Basic Syntax

# Heading 1
## Heading 2
### Heading 3

Paragraph with **bold** and *italic* text.

- Bullet list
- Another item
  - Nested item

1. Numbered list
2. Another item

> Blockquote

`inline code`

[Link](https://example.com)

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| A        | B        | C        |
| D        | E        | F        |

Code Blocks

```python
def hello():
    print("Hello, World!")
```

MermaidJS Diagrams

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Result A]
    C -->|No| E[Result B]
```

Supported diagram types:

• Flowcharts (graph TD, graph LR)
• Sequence diagrams (sequenceDiagram)
• Class diagrams (classDiagram)
• State diagrams (stateDiagram-v2)
• ER diagrams (erDiagram)
• And all other Mermaid diagram types

Note: Tall diagrams are automatically scaled to fit within a single page (max-height: 700px) while preserving aspect ratio.

Images

Images in Markdown are automatically embedded as Base64 data URIs:

![Local image](./images/photo.png)
![Remote image](https://example.com/image.png)

Supported sources:

• Relative paths: ./images/photo.png (resolved from Markdown file location)
• Absolute paths: /home/user/image.png
• HTTP/HTTPS URLs: Remote images are fetched and embedded

This ensures PDFs are fully portable with no external dependencies.

Special HTML Classes

Use these HTML classes in your Markdown for special styling:

Summary Box (Green)

<div class="summary">
Important summary points here.
</div>

Warning Box (Orange)

<div class="warning">
Warning message here.
</div>

Info Box (Blue)

<div class="info">
Additional information here.
</div>

Pros/Cons

<div class="pros">
Pros: High scalability
</div>

<div class="cons">
Cons: Initial cost
</div>

Disclaimer

<div class="disclaimer">
This report is for informational purposes only.
</div>

Page Break

<div class="page-break"></div>

Python API

from gospelo_md2pdf import convert_md_to_pdf

# Basic usage
convert_md_to_pdf("report.md")

# With options
convert_md_to_pdf(
    input_file="report.md",
    output_file="output.pdf",
    output_dir="./pdf",
    css_file="custom.css",
    keep_html=True,
    lang="ja",
    verbose=True
)

Troubleshooting

Japanese text not rendering

Check if Japanese fonts are installed:

fc-list :lang=ja | head -5

WeasyPrint library errors on macOS

Set the library path:

export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH

Add to ~/.zshrc for persistence:

echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
source ~/.zshrc

Mermaid diagrams not rendering

1. Verify network connectivity to kroki.io
2. For Web Claude: Add kroki.io to allowed domains (Settings → Capabilities → Additional allowed domains)
3. Check error messages for "Cannot connect to Kroki"

Requirements

• Python >= 3.10
• weasyprint >= 60.0
• markdown >= 3.5.0
• System: pango, glib, gdk-pixbuf (see Installation)
• Network: Access to kroki.io (for Mermaid diagrams)

Dependencies and Acknowledgements

This project uses the following open-source libraries. Full license texts are included in the LICENSE file.

System Libraries (Dynamically Linked)

Note: System libraries are dynamically linked and not bundled with this package.

Fonts (Recommended)

Note: Fonts are not bundled with this package. Users install them separately.

License

MIT License - see LICENSE for details.

Author

NoStudio LLC (goro-hayakawa@no-studio.net)

Documentation

• 日本語ドキュメント (Japanese)
• Agent Skills Quick Start
• CSS Template Guide
• Changelog

Links

• GitHub Repository
• Issue Tracker
• PyPI Package