Willem van den Ende
e248395557
- Update docster.cabal to modern format with GHC 9.12.2 compatibility - Fix Mermaid code block detection using getDefaultExtensions - Switch from SVG to PNG output for PDF compatibility - Add CLAUDE.md with development instructions - Update tooling from mise to ghcup for Haskell management Known issues: - Generated diagram files are created in root directory instead of alongside source files - PDF generation fails with LaTeX errors for complex documents (missing \tightlist support) - HTML output lacks proper DOCTYPE (quirks mode) - Debug output still present in code 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
78 lines
2.1 KiB
Markdown
78 lines
2.1 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
|
|
- `processMermaid` (app/Main.hs:21-34) - Transforms Mermaid code blocks into SVG images
|
|
- `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 SVG files using mermaid-cli (mmdc)
|
|
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 pdflatex)
|
|
- 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. |