49 lines
1.6 KiB
Markdown
49 lines
1.6 KiB
Markdown
# Docster — Project Guide
|
|
|
|
Docster is a Haskell CLI tool: Markdown + embedded Mermaid diagrams → PDF, HTML, or DOCX.
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
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.
|