docster/agents.md

Docster — Project Guide

Docster is a Haskell CLI tool: Markdown + embedded Mermaid diagrams → PDF, HTML, or DOCX.

Quick Commands

stack build          # build
stack test           # run tests
stack exec docster -- -pdf file.md   # convert to PDF
stack exec docster -- -html file.md  # convert to HTML
stack exec docster -- -docx file.md  # convert to DOCX
stack exec docster -- -pdf sample.md # test with a single file
stack clean          # clean build artifacts

Structure

docster.cabal        # package definition
stack.yaml           # GHC 9.12.2, lts-24.34
app/Main.hs          # everything — entry point + all logic (~70 lines)
test/                # HSpec tests (TransformSpec.hs)

How It Works

1. Parse Markdown via Pandoc AST
2. Walk the AST, find Mermaid code blocks
3. Run mmdc (mermaid-cli) to render each block → SVG (for HTML) or high-res PNG (for PDF)
4. Replace code blocks with image references in the AST
5. Compile final output via Pandoc (LaTeX/XeLaTeX for PDF, native for HTML/DOCX)

Key functions in Main.hs:

• transformDoc — AST walker
• processMermaidBlock — calls mmdc, returns image reference
• compileToPDF / compileToHTML / compileToDOCX — final Pandoc compilation

Dependencies

System: TeX Live (for PDF), npm install -g @mermaid-js/mermaid-cli Haskell: Pandoc library, Stack manages GHC automatically

Common Gotchas

• Text vs String: Codebase mixes Data.Text and String. Use T.pack/T.unpack for conversions.
• PDF needs LaTeX: BasicTeX/TinyTeX + tlmgr for missing packages.
• mmdc in PATH: mermaid-cli must be globally installed and on PATH.