Homebrew

brew tap alnah/tap
brew install alnah/tap/picoloom

Update later with:

brew upgrade alnah/tap/picoloom

On a fresh machine without Chrome installed yet, picoloom doctor stays strict by default. Use picoloom doctor --allow-managed-browser to validate the managed Chromium bootstrap path used on first run.

Docker

docker pull ghcr.io/alnah/picoloom:latest

Binary Download

Download pre-built binaries from GitHub Releases.

picoloom <command> [flags] [args]
Commands:   convert      Convert markdown files to PDF   config       Manage configuration files   doctor       Check system configuration   completion   Generate shell completion script   version      Show version information   help         Show help for a command
picoloom convert <input> [flags]
Input/Output:   -o, --output <path>       Output file or directory   -c, --config <name>       Config file name or path   -w, --workers <n>         Parallel workers (0 = auto)   -t, --timeout <duration>  PDF generation timeout (default: 30s)                             Examples: 30s, 2m, 1m30s
Author:       --author-name <s>     Author name       --author-title <s>    Author professional title       --author-email <s>    Author email       --author-org <s>      Organization name       --author-phone <s>    Author phone number       --author-address <s>  Author postal address       --author-dept <s>     Author department
Document:       --doc-title <s>       Document title ("" = auto from H1)       --doc-subtitle <s>    Document subtitle       --doc-version <s>     Version string       --doc-date <s>        Date (see Date Formats section)       --doc-client <s>      Client name       --doc-project <s>     Project name       --doc-type <s>        Document type       --doc-id <s>          Document ID/reference       --doc-desc <s>        Document description
Page:   -p, --page-size <s>       letter, a4, legal (default: letter)       --orientation <s>     portrait, landscape (default: portrait)       --margin <f>          Margin in inches (default: 0.5)
Footer:       --footer-position <s> left, center, right (default: right)       --footer-text <s>     Custom footer text       --footer-page-number  Show page numbers       --footer-doc-id       Show document ID in footer       --no-footer           Disable footer
Cover:       --cover-logo <path>   Logo path or URL       --cover-dept          Show author department on cover       --no-cover            Disable cover page
Signature:       --sig-image <path>    Signature image path       --no-signature        Disable signature block
Table of Contents:       --toc-title <s>       TOC heading text       --toc-min-depth <n>   Min heading depth (1-6, default: 2)                             1=H1, 2=H2, etc. Use 2 to skip title       --toc-max-depth <n>   Max heading depth (1-6, default: 3)       --no-toc              Disable table of contents
Watermark:       --wm-text <s>         Watermark text       --wm-color <s>        Color hex (default: #888888)       --wm-opacity <f>      Opacity 0.0-1.0 (default: 0.1)       --wm-angle <f>        Angle in degrees (default: -45)       --no-watermark        Disable watermark
Page Breaks:       --break-before <s>    Break before headings: h1,h2,h3       --orphans <n>         Min lines at page bottom (default: 2)       --widows <n>          Min lines at page top (default: 2)       --no-page-breaks      Disable page break features
Assets & Styling:       --style <name|path>   CSS style name or file path (default: default)                             Name: uses embedded or custom asset (e.g., "technical")                             Path: reads file directly (contains / or \)       --template <name|path> Template set name or directory path       --asset-path <dir>    Custom asset directory (overrides config)       --no-style            Disable CSS styling
Debug Output:       --html                Output HTML alongside PDF       --html-only           Output HTML only, skip PDF generation
Output Control:   -q, --quiet               Only show errors   -v, --verbose             Show detailed timing
picoloom config init [flags]
Config Init:       --output <path>       Output path for generated config (default: ./picoloom.yaml)       --force               Overwrite destination if it exists       --no-input            Use defaults without interactive prompts

# Single file with custom output
picoloom convert -o report.pdf input.md
Batch with config
picoloom convert -c work ./docs/ -o ./pdfs/
Custom CSS, no footer
picoloom convert --style ./custom.css --no-footer document.md
A4 landscape with 1-inch margins
picoloom convert -p a4 --orientation landscape --margin 1.0 document.md
With watermark
picoloom convert --wm-text "DRAFT" --wm-opacity 0.15 document.md
Override document title
picoloom convert --doc-title "Final Report" document.md
Page breaks before H1 and H2 headings
picoloom convert --break-before h1,h2 document.md
Use embedded style by name
picoloom convert --style technical document.md
Debug: output HTML alongside PDF
picoloom convert --html document.md
Debug: output HTML only (no PDF)
picoloom convert --html-only document.md
Use custom assets directory
picoloom convert --asset-path ./my-assets document.md
Interactive config wizard
picoloom config init
Non-interactive config generation (CI/scripts)
picoloom config init --no-input --output ./configs/work.yaml --force

Generate shell completion scripts for tab-completion of commands, flags, and file arguments:

# Bash - add to ~/.bashrc
eval "$(picoloom completion bash)"
Zsh - add to ~/.zshrc
eval "$(picoloom completion zsh)"
Fish - save to completions directory
picoloom completion fish > ~/.config/fish/completions/picoloom.fish
PowerShell - add to $PROFILE
picoloom completion powershell | Out-String | Invoke-Expression

| Code | Name | Description | |------|------|-------------| | 0 | Success | Conversion completed successfully | | 1 | General | Unexpected or unclassified error | | 2 | Usage | Invalid flags, configuration, or validation failure | | 3 | I/O | File not found, permission denied, write failure | | 4 | Browser | Chrome not found, connection failed, timeout |

Example usage in scripts:

picoloom convert document.md
case $? in
    0) echo "Success" ;;
    2) echo "Check your flags or config" ;;
    3) echo "Check file permissions" ;;
    4) echo "Check Chrome installation" ;;
    *) echo "Unknown error" ;;
esac

Diagnose system configuration before running conversions:

picoloom doctor           # Human-readable output
picoloom doctor --json    # JSON output for CI/scripts
picoloom doctor --allow-managed-browser

Checks performed:

• Chrome/Chromium: binary exists, version, sandbox status
• Environment: container detection (Docker, Podman, Kubernetes)
• System: temp directory writability

Exit codes:

• 0 - All checks passed (including warnings)
• 1 - Errors found (conversion will likely fail)

# Fail pipeline early if setup is broken
picoloom doctor --json | jq -e '.status != "errors"' || exit 1

# Convert a single file
docker run --rm -v $(pwd):/data ghcr.io/alnah/picoloom convert document.md
Convert with output path
docker run --rm -v $(pwd):/data ghcr.io/alnah/picoloom convert -o output.pdf input.md
Batch convert directory
docker run --rm -v $(pwd):/data ghcr.io/alnah/picoloom convert ./docs/ -o ./pdfs/

Note: The official Docker image has all dependencies pre-installed. For custom images, see Troubleshooting.

GitHub Actions:

- name: Generate PDFs   env:     PICOLOOM_STYLE: technical     PICOLOOMAUTHORORG: ${{ github.repository_owner }}     PICOLOOMDOCVERSION: ${{ github.ref_name }}     PICOLOOMWATERMARKTEXT: ${{ github.ref_name == 'main' && '' || 'DRAFT' }}   run: picoloom convert ./docs/ -o ./output/

GitLab CI:

pdf:   variables:     PICOLOOM_STYLE: corporate     PICOLOOMOUTPUTDIR: ./artifacts/pdf     PICOLOOMDOCDATE: auto   script:     - picoloom convert ./docs/

Docker:

docker run --rm \   -e PICOLOOM_STYLE=technical \   -e PICOLOOMAUTHORORG="Acme Corp" \   -e RODNOSANDBOX=1 \   -v $(pwd):/data \   ghcr.io/alnah/picoloom convert ./docs/

# ~/.config/picoloom/work.yaml
Input/Output directories
input:
  defaultDir: './docs/markdown' # Default input when no arg provided
output:   defaultDir: './docs/pdf' # Default output when no -o flag
PDF generation timeout (default: 30s)
Use Go duration format: 30s, 2m, 1m30s
timeout: '1m'
Shared author info (used by cover and signature)
author:
  name: 'John Doe'
  title: 'Senior Developer'
  email: 'john@example.com'
  organization: 'Acme Corp'
  phone: '+1 555-0123'
  address: |
    123 Main Street
    San Francisco, CA 94102
  department: 'Engineering'
Shared document metadata (used by cover and footer)
document:
  title: '' # "" = auto from H1 or filename
  subtitle: 'Internal Document'
  version: 'v1.0'
  # Date formats:
  #   - Literal: '2025-01-11'
  #   - Auto (ISO): 'auto' -> 2025-01-11
  #   - Auto with format: 'auto:DD/MM/YYYY' -> 11/01/2025
  #   - Auto with preset: 'auto:long' -> January 11, 2025
  # Presets: iso, european, us, long
  # Tokens: YYYY, YY, MMMM, MMM, MM, M, DD, D
  # Escaping: [text] -> literal text
  date: 'auto'
  clientName: 'Client Corp'
  projectName: 'Project Alpha'
  documentType: 'Technical Specification'
  documentID: 'DOC-2025-001'
  description: 'Technical documentation for Project Alpha'
Page layout
page:
  size: 'a4'           # letter (default), a4, legal
  orientation: 'portrait' # portrait (default), landscape
  margin: 0.75         # inches, 0.25-3.0 (default: 0.5)
Styling
Available styles:
  - default: minimal, neutral styling (applied when no style specified)
  - technical: system-ui, clean borders, GitHub syntax highlighting
  - creative: colorful headings, badges, bullet points
  - academic: Georgia/Times serif, 1.8 line height, academic tables
  - corporate: Arial/Helvetica, blue accents, business style
  - legal: Times New Roman, double line height, wide margins
  - invoice: Arial, optimized tables, minimal cover
  - manuscript: Courier New mono, scene breaks, simplified cover
Accepts name (e.g., "technical") or path (e.g., "./custom.css")
style: 'technical'
assets:   basePath: '' # "" = use embedded assets
Cover page
cover:
  enabled: true
  logo: '/path/to/logo.png' # path or URL
  showDepartment: true      # show author.department on cover
Table of contents
toc:
  enabled: true
  title: 'Table of Contents'
  minDepth: 2 # 1-6 (default: 2, skips H1)
  maxDepth: 3 # 1-6 (default: 3)
Footer
footer:
  enabled: true
  position: 'center'     # left, center, right (default: right)
  showPageNumber: true
  showDocumentID: true   # show document.documentID in footer
  text: ''               # optional custom text
Signature block
signature:
  enabled: true
  imagePath: '/path/to/signature.png'
  links:
    - label: 'GitHub'
      url: 'https://github.com/johndoe'
    - label: 'LinkedIn'
      url: 'https://linkedin.com/in/johndoe'
Watermark
watermark:
  enabled: false
  text: 'DRAFT'      # DRAFT, CONFIDENTIAL, SAMPLE, PREVIEW, etc.
  color: '#888888'   # hex color (default: #888888)
  opacity: 0.1       # 0.0-1.0 (default: 0.1, recommended: 0.05-0.15)
  angle: -45         # -90 to 90 (default: -45 = diagonal)
Page breaks
pageBreaks:
  enabled: true
  beforeH1: true
  beforeH2: false
  beforeH3: false
  orphans: 2 # min lines at page bottom, 1-5 (default: 2)
  widows: 2  # min lines at page top, 1-5 (default: 2)

When your markdown contains relative image paths like , specify the source directory so they resolve correctly:

content, _ := os.ReadFile("docs/report.md")
result, err := conv.Convert(ctx, picoloom.Input{     Markdown:  string(content),     SourceDir: "docs/", // Images resolve relative to this directory })

The CLI automatically sets SourceDir to the input file's directory, so relative images work out of the box.

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    Cover: &picoloom.Cover{
        Title:        "Project Report",
        Subtitle:     "Q4 2025 Analysis",
        Author:       "John Doe",
        AuthorTitle:  "Senior Analyst",
        Organization: "Acme Corp",
        Date:         "2025-12-15",
        Version:      "v1.0",
        Logo:         "/path/to/logo.png", // or URL
        ClientName:   "Client Corp",       // extended metadata
        ProjectName:  "Project Alpha",
        DocumentType: "Technical Report",
        DocumentID:   "DOC-2025-001",
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    TOC: &picoloom.TOC{
        Title:    "Contents",
        MinDepth: 2, // Start at h2 (skip document title)
        MaxDepth: 3, // Include up to h3
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    Footer: &picoloom.Footer{
        ShowPageNumber: true,
        Position:       "center",
        Date:           "2025-12-15",
        Status:         "DRAFT",
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    Signature: &picoloom.Signature{
        Name:         "John Doe",
        Title:        "Senior Developer",
        Email:        "john@example.com",
        Organization: "Acme Corp",
        Phone:        "+1 555-0123",  // extended metadata
        Department:   "Engineering",
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    Watermark: &picoloom.Watermark{
        Text:    "CONFIDENTIAL",
        Color:   "#888888",
        Opacity: 0.1,
        Angle:   -45,
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    Page: &picoloom.PageSettings{
        Size:        picoloom.PageSizeA4,
        Orientation: picoloom.OrientationLandscape,
        Margin:      1.0, // inches
    },
})

result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    PageBreaks: &picoloom.PageBreaks{
        BeforeH1: true, // Page break before H1 headings
        BeforeH2: true, // Page break before H2 headings
        Orphans:  3,    // Min 3 lines at page bottom
        Widows:   3,    // Min 3 lines at page top
    },
})

The CSS field in Input accepts a CSS string that is injected into the HTML for this specific conversion:

// CSS string injected into this document only
result, err := conv.Convert(ctx, picoloom.Input{
    Markdown: content,
    CSS: 
        body { font-family: Georgia, serif; }
        h1 { color: #2c3e50; }
        code { background: #f8f9fa; }
    ,
})

This is useful for:

• Document-specific styling that differs from the base theme
• Dynamically generated CSS (e.g., user-selected colors)
• Quick overrides without changing service configuration

For services, APIs, queues, or other multi-tenant environments, reject oversized Markdown before calling Convert:

const maxMarkdownBytes = 1 << 20 // 1 MiB
if len(markdown) > maxMarkdownBytes {
    return fmt.Errorf("markdown exceeds %d bytes", maxMarkdownBytes)
}
result, err := conv.Convert(ctx, picoloom.Input{Markdown: markdown})

Picoloom intentionally does not expose a library size-limit option. Local CLI and library users may convert large documents, while server callers can enforce limits that match their own request, tenant, and storage policies.

Markdown parsing is CPU-bound, and Goldmark does not accept a standard context.Context cancellation signal while parsing. Picoloom checks cancellation before and after parsing, but a parse already in progress may continue briefly after the caller cancels. Caller-side byte limits are the reliable guard that stops oversized input before preprocessing and parsing begin.

Override embedded CSS styles and HTML templates:

// Option 1: Use embedded style by name
conv, err := picoloom.NewConverter(picoloom.WithStyle("technical"))
// Option 2: Load CSS from file path conv, err := picoloom.NewConverter(picoloom.WithStyle("./custom.css"))
// Option 3: Provide CSS content directly conv, err := picoloom.NewConverter(picoloom.WithStyle("body { font-family: Georgia; }"))
// Option 4: Load from custom directory (with fallback to embedded) conv, err := picoloom.NewConverter(picoloom.WithAssetPath("/path/to/assets"))
// Option 5: Provide template set directly ts := picoloom.NewTemplateSet("custom", coverHTML, signatureHTML) conv, err := picoloom.NewConverter(picoloom.WithTemplateSet(ts))
// Option 6: Full control with custom loader loader, err := picoloom.NewAssetLoader("/path/to/assets") if err != nil {     log.Fatal(err) } conv, err := picoloom.NewConverter(picoloom.WithAssetLoader(loader))

WithStyle accepts a style name, file path, or CSS content:

• Name: "technical" loads the embedded style
• Path: "./custom.css" reads from file (detected by / or \)
• CSS: "body { ... }" uses content directly (detected by {)

/path/to/assets/
├── styles/
│   ├── default.css      # Override default style
│   └── technical.css    # Add custom style
└── templates/
    └── default/         # Template set directory
        ├── cover.html       # Cover page template
        └── signature.html   # Signature block template

Available embedded styles: default, technical, creative, academic, corporate, legal, invoice, manuscript

Missing files fall back to embedded defaults silently.

Note: Converter-level options (WithAssetPath, WithStyle, WithAssetLoader) configure the base theme for all conversions. To add document-specific CSS on top of the base theme, use Input.CSS in the Convert() call.

For batch conversion, use ConverterPool to process multiple files in parallel:

package main
import (     "context"     "log"     "os"     "sync"
"github.com/alnah/picoloom/v2" )
func main() {     // Create pool with 4 workers (each has its own browser instance)     pool := picoloom.NewConverterPool(4)     defer pool.Close()
files := []string{"doc1.md", "doc2.md", "doc3.md", "doc4.md"}     var wg sync.WaitGroup
for _, file := range files {         wg.Add(1)         go func(f string) {             defer wg.Done()
conv := pool.Acquire()             if conv == nil {                 log.Printf("failed to acquire converter: %v", pool.InitError())                 return             }             defer pool.Release(conv)
content, _ := os.ReadFile(f)             result, err := conv.Convert(context.Background(), picoloom.Input{                 Markdown: string(content),             })             if err != nil {                 log.Printf("convert %s: %v", f, err)                 return             }             os.WriteFile(f+".pdf", result.PDF, 0644)         }(file)     }     wg.Wait() }

Use picoloom.ResolvePoolSize(0) to auto-calculate a conservative pool size based on CPU cores. The automatic size is clamped to picoloom.MaxPoolSize because each Converter owns a browser process and may use significant memory.

Explicit library pool sizes are not clamped. For example, picoloom.NewConverterPool(16) and picoloom.ResolvePoolSize(16) request 16 converters. Use explicit values above picoloom.MaxPoolSize only when your environment has enough memory and process capacity. The CLI is stricter: --workers is capped at picoloom.MaxPoolSize.