Configuration Reference¶

Complete reference for all Jekyll Pandoc Exports configuration options.

Basic Configuration¶

Add to your _config.yml:

pandoc_exports:
  enabled: true
  output_dir: 'downloads'
  collections: ['pages', 'posts']
  incremental: true

All Configuration Options¶

pandoc_exports:
  # Core Settings
  enabled: true                     # Enable/disable plugin (default: true)
  output_dir: 'downloads'           # Output directory (default: site root)
  collections: ['pages', 'posts']   # Collections to process
  incremental: true                 # Only regenerate changed files

  # Performance & Debugging
  debug: true                       # Enable debug logging
  max_file_size: 10000000          # Max file size in bytes (10MB)
  performance_monitoring: true      # Log processing times
  strict_size_limit: false         # Fail on size limit (vs warn)

  # PDF Generation
  pdf_options:
    variable: 'geometry:margin=0.75in'
    toc: true

  # Pandoc Options
  pandoc_options:
    toc: true
    number-sections: true

  # Content Processing
  unicode_cleanup: true
  title_cleanup:
    - '<title>.*?</title>'
    - '<h1[^>]*>.*?Site Title.*?</h1>'

  # Image Handling
  image_path_fixes:
    - pattern: 'src="/assets/images/'
      replacement: 'src="{{site.dest}}/assets/images/'

  # Download Links
  inject_downloads: true
  download_class: 'pandoc-downloads no-print'
  download_style: 'margin: 20px 0; padding: 15px; background-color: #f8f9fa;'

  # Template System
  template:
    header: '<div class="export-header">Document Export</div>'
    footer: '<div class="export-footer">Generated by Jekyll</div>'
    css: '.export-header { font-weight: bold; margin-bottom: 20px; }'

Configuration Details¶

Core Settings¶

Option	Type	Default	Description
`enabled`	Boolean	`true`	Enable/disable the plugin
`output_dir`	String	`''`	Custom output directory for exports
`collections`	Array	`['pages', 'posts']`	Collections to process
`incremental`	Boolean	`false`	Only regenerate files when source changes

Performance Settings¶

Option	Type	Default	Description
`debug`	Boolean	`false`	Enable debug logging with detailed output
`max_file_size`	Integer	`10000000`	Maximum file size in bytes before warning
`performance_monitoring`	Boolean	`false`	Log processing times for each file
`strict_size_limit`	Boolean	`false`	Fail build on size limit (vs warning)

PDF Options¶

Standard Pandoc PDF options:

pdf_options:
  variable: 'geometry:margin=1in'     # Page margins
  variable: 'fontsize=12pt'           # Font size
  variable: 'documentclass=article'   # Document class
  toc: true                           # Table of contents
  number-sections: true               # Number sections

Pandoc Options¶

Additional Pandoc command-line options:

pandoc_options:
  toc: true                    # Table of contents
  toc-depth: 3                 # TOC depth
  number-sections: true        # Number sections
  highlight-style: 'github'    # Code highlighting
  standalone: true             # Standalone document

Content Processing¶

Option	Type	Default	Description
`unicode_cleanup`	Boolean	`true`	Remove problematic Unicode characters for LaTeX
`title_cleanup`	Array	`[]`	Regex patterns to remove from PDF HTML
`image_path_fixes`	Array	`[]`	Path replacements for images

Template System¶

Customize export appearance:

template:
  header: '<div class="header">Company Name</div>'
  footer: '<div class="footer">Page {{page}}</div>'
  css: |
    .header { 
      font-weight: bold; 
      text-align: center; 
      border-bottom: 1px solid #ccc; 
    }
    .footer { 
      text-align: center; 
      font-size: 10pt; 
      color: #666; 
    }

Per-Page Configuration¶

Override settings in page front matter:

---
title: Custom Document
docx: true
pdf: true
pdf_options:
  variable: 'geometry:margin=0.5in'
  toc: false
---

Collection-Specific Settings¶

Process different collections with different settings:

pandoc_exports:
  collections: ['pages', 'posts', 'portfolio']

  # Future: Per-collection configuration
  # collection_settings:
  #   portfolio:
  #     output_dir: 'portfolio-exports'
  #     template:
  #       header: '<div>Portfolio Item</div>'

Environment-Specific Configuration¶

Use Jekyll's environment features:

# _config.yml (development)
pandoc_exports:
  enabled: true
  debug: true

# _config_production.yml
pandoc_exports:
  enabled: true
  debug: false
  performance_monitoring: true

CSS for Print Styling¶

Hide download links when printing:

@media print {
  .no-print {
    display: none !important;
  }

  .pandoc-downloads {
    display: none !important;
  }
}

Validation¶

The plugin validates configuration on startup:

Checks for required dependencies (Pandoc, LaTeX)
Validates file paths and permissions
Reports configuration issues with helpful messages

Examples¶

Blog with Custom Styling¶

pandoc_exports:
  collections: ['posts']
  output_dir: 'blog-exports'
  template:
    header: '<div class="blog-header">My Blog</div>'
    css: '.blog-header { color: #2c3e50; font-size: 18pt; }'
  pdf_options:
    variable: 'geometry:margin=0.75in'
    toc: true

Documentation Site¶

pandoc_exports:
  collections: ['pages', 'docs']
  output_dir: 'documentation'
  unicode_cleanup: true
  pandoc_options:
    toc: true
    number-sections: true
    highlight-style: 'github'
  template:
    header: '<div>Documentation v{{site.version}}</div>'
    footer: '<div>© {{site.time | date: "%Y"}} Company</div>'

Portfolio Site¶

pandoc_exports:
  collections: ['portfolio']
  output_dir: 'portfolio-pdfs'
  inject_downloads: false  # Custom download handling
  template:
    css: |
      body { font-family: 'Helvetica', sans-serif; }
      .portfolio-header { text-align: center; margin-bottom: 30px; }