Willem van den Ende
7f1f1aeeb0
Problem: SVG diagrams had missing text in PDFs due to Inkscape conversion issues with foreignObject elements used by Mermaid for HTML text rendering. Solution: Implement format-specific optimal generation: - HTML: SVG files for perfect vector scaling and text rendering - PDF: High-resolution PNG files (3x scale) for sharp images with readable text Changes: - Generate SVG for HTML output using standard mmdc command - Generate PNG for PDF output using mmdc with --scale 3 for high resolution - Remove SVG LaTeX package dependency and Inkscape requirement - Update documentation to reflect the dual-format approach Results: - HTML: Crisp, scalable vector diagrams with perfect text - PDF: Sharp, high-resolution raster diagrams with clear text - No external dependencies beyond mermaid-cli 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
78 lines
2.2 KiB
Markdown
78 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Docster is a Haskell CLI tool that converts Markdown files with embedded Mermaid diagrams into PDF or HTML. It processes Mermaid code blocks by rendering them to SVG images and embedding them in the output.
|
|
|
|
## Development Commands
|
|
|
|
### Build
|
|
```bash
|
|
cabal build
|
|
```
|
|
|
|
### Run
|
|
```bash
|
|
# Convert to PDF
|
|
cabal run docster -- -pdf path/to/file.md
|
|
|
|
# Convert to HTML
|
|
cabal run docster -- -html path/to/file.md
|
|
```
|
|
|
|
### Test a single file
|
|
```bash
|
|
cabal run docster -- -pdf mermaid-to-svg/sample.md
|
|
```
|
|
|
|
### Clean build artifacts
|
|
```bash
|
|
cabal clean
|
|
```
|
|
|
|
### Interactive development
|
|
```bash
|
|
cabal repl
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The application consists of:
|
|
|
|
1. **Main.hs** (app/Main.hs:1-69) - Entry point and core logic
|
|
- `processMermaidBlock` (app/Main.hs:54-79) - Transforms Mermaid code blocks into images (SVG for HTML, high-res PNG for PDF)
|
|
- `transformDoc` (app/Main.hs:36-37) - Walks the Pandoc AST to process all blocks
|
|
- `compileToPDF` (app/Main.hs:47-58) - Converts Markdown to PDF using LaTeX
|
|
- `compileToHTML` (app/Main.hs:60-68) - Converts Markdown to HTML
|
|
|
|
The tool uses Pandoc's AST transformation capabilities to:
|
|
1. Parse Markdown input
|
|
2. Find Mermaid code blocks
|
|
3. Generate image files using mermaid-cli (mmdc) - SVG for HTML, high-resolution PNG for PDF
|
|
4. Replace code blocks with image references
|
|
5. Output final PDF/HTML
|
|
|
|
## Dependencies
|
|
|
|
External requirements:
|
|
- GHC 9.12.2 and Cabal 3.16 (install via ghcup)
|
|
- Pandoc library
|
|
- TeX Live (for PDF generation via XeLaTeX)
|
|
- Mermaid CLI (`npm install -g @mermaid-js/mermaid-cli`)
|
|
|
|
To install GHC and Cabal:
|
|
```bash
|
|
source ~/.ghcup/env && ghcup install ghc 9.12.2
|
|
source ~/.ghcup/env && ghcup install cabal 3.16.0.0
|
|
source ~/.ghcup/env && ghcup set ghc 9.12.2
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
1. **Missing LaTeX packages**: PDF generation requires a LaTeX distribution. Install BasicTeX or TinyTeX and use tlmgr to add packages as needed.
|
|
|
|
2. **Mermaid CLI not found**: Ensure mmdc is in PATH after installing @mermaid-js/mermaid-cli globally.
|
|
|
|
3. **Type errors with Text vs String**: The codebase mixes Data.Text and String. Use T.pack/T.unpack for conversions. |