jekyll-pandoc-exports 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5364fb46cdd2204734b7da5c0839a52718720a21716e3e1f7ba44e4575793af
+  data.tar.gz: 54488d1f7b0cb3d922c270d1bd0073782532c4b9bc83613af65bab743e19b8a8
+SHA512:
+  metadata.gz: 68956bc865a4f121db2383f76ee4da4b182738dca373a12170d303a1562c384bb8acee5fb08a7b345793eb5872cea2e1739b34603b360c436d8c61a7382da2af
+  data.tar.gz: f64ba616557c883f967557a6f933cc0e46ad289866c3deb57aac7c0ac5ee98a354c742319fda9e1fb0cf036b8f012838e345af0177929650e60d1df7accc6778

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-01-XX
+
+### Added
+- Initial release of jekyll-pandoc-exports plugin
+- DOCX generation using pandoc-ruby
+- PDF generation with LaTeX support
+- Configurable PDF options (margins, paper size, etc.)
+- Unicode cleanup for LaTeX compatibility
+- Automatic download link injection
+- Configurable HTML cleanup patterns
+- Image path fixing for pandoc conversion
+- Print-friendly CSS class support
+- Per-page PDF option overrides

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael McGarrah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# Jekyll Pandoc Exports Plugin
+
+A Jekyll plugin that automatically generates DOCX and PDF exports of your pages using Pandoc.
+
+## Features
+
+- Generate Word documents (.docx) and PDFs from Jekyll pages, posts, and collections
+- Configurable output directories for organized file management
+- Incremental builds (only regenerate changed files)
+- Automatic dependency validation (Pandoc/LaTeX)
+- Configurable PDF options (margins, paper size, etc.)
+- Automatic Unicode cleanup for LaTeX compatibility
+- Configurable HTML cleanup patterns
+- Auto-injection of download links
+- Flexible image path fixing
+- Print-friendly CSS class support
+
+## Installation
+
+### 1. Install Dependencies
+
+First, install Pandoc and LaTeX (for PDF generation):
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install pandoc texlive-latex-base texlive-fonts-recommended texlive-latex-extra
+
+# macOS
+brew install pandoc
+brew install --cask mactex
+```
+
+### 2. Add to Gemfile
+
+Add to your Jekyll site's Gemfile:
+
+```ruby
+gem "jekyll-pandoc-exports"
+```
+
+### 3. Enable Plugin
+
+Add to your `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-pandoc-exports
+```
+
+## Usage
+
+### Basic Usage
+
+Add front matter to any page you want to export:
+
+```yaml
+---
+title: My Document
+docx: true    # Generate Word document
+pdf: true     # Generate PDF
+---
+```
+
+### Configuration
+
+Add configuration to your `_config.yml`:
+
+```yaml
+pandoc_exports:
+  enabled: true
+  output_dir: 'downloads'           # Custom output directory (optional)
+  collections: ['pages', 'posts']   # Collections to process
+  incremental: true                 # Only regenerate changed files
+  pdf_options:
+    variable: 'geometry:margin=0.75in'
+  unicode_cleanup: true
+  inject_downloads: true
+  download_class: 'pandoc-downloads no-print'
+  title_cleanup:
+    - '<title>.*?</title>'
+    - '<h1[^>]*>.*?Site Title.*?</h1>'
+  image_path_fixes:
+    - pattern: 'src="/assets/images/'
+      replacement: 'src="{{site.dest}}/assets/images/'
+```
+
+### Configuration Options
+
+- `enabled`: Enable/disable the plugin (default: true)
+- `output_dir`: Custom output directory for exports (default: site root)
+- `collections`: Array of collections to process (default: ['pages', 'posts'])
+- `incremental`: Only regenerate files when source changes (default: false)
+- `pdf_options`: Pandoc options for PDF generation (default: 1in margins)
+- `unicode_cleanup`: Remove problematic Unicode characters for LaTeX (default: true)
+- `inject_downloads`: Auto-inject download links into pages (default: true)
+- `download_class`: CSS class for download links (default: 'pandoc-downloads no-print')
+- `title_cleanup`: Array of regex patterns to remove from PDF HTML
+- `image_path_fixes`: Array of path replacements for images
+
+### Per-Page PDF Options
+
+Override PDF options for specific pages:
+
+```yaml
+---
+title: My Document
+pdf: true
+pdf_options:
+  variable: 'geometry:margin=0.5in'
+---
+```
+
+### CSS for Print Hiding
+
+Add to your main CSS to hide download links when printing:
+
+```css
+@media print {
+  .no-print {
+    display: none !important;
+  }
+}
+```
+
+## Generated Files
+
+The plugin generates files with the same name as your markdown file:
+
+- `my-page.md` → `my-page.docx` and `my-page.pdf`
+- Accessible at `/my-page.docx` and `/my-page.pdf`
+
+## Download Links
+
+When `inject_downloads` is enabled, the plugin automatically adds download links to pages that generate exports. Links are inserted after the first heading or at the beginning of the body.
+
+## Publishing to RubyGems
+
+If you want to publish this gem to RubyGems:
+
+### 1. Build the gem:
+```bash
+gem build jekyll-pandoc-exports.gemspec
+```
+
+### 2. Test locally (optional):
+```bash
+gem install ./jekyll-pandoc-exports-1.0.0.gem
+```
+
+### 3. Publish to RubyGems:
+```bash
+# First time setup (if needed)
+gem signin
+
+# Publish the gem
+gem push jekyll-pandoc-exports-1.0.0.gem
+```
+
+## Gem Structure
+
+- **`jekyll-pandoc-exports.gemspec`** - Gem specification with dependencies
+- **`lib/jekyll-pandoc-exports.rb`** - Main entry point
+- **`lib/jekyll-pandoc-exports/version.rb`** - Version management
+- **`lib/jekyll-pandoc-exports/generator.rb`** - Plugin code
+- **`README.md`** - Complete documentation
+- **`LICENSE`** - MIT license
+- **`CHANGELOG.md`** - Version history
+- **`Gemfile`** - Development dependencies
+- **`Rakefile`** - Build tasks
+
+## Troubleshooting
+
+### LaTeX Errors
+- Ensure LaTeX packages are installed
+- Enable `unicode_cleanup` to remove problematic characters
+- Add custom cleanup patterns to `title_cleanup`
+
+### Image Issues
+- Configure `image_path_fixes` for your site's image paths
+- Use absolute paths in the replacement patterns
+
+### Missing Files
+- Check that Pandoc is installed and accessible
+- Verify file permissions in the `_site` directory
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/lib/jekyll-pandoc-exports/generator.rb

@@ -0,0 +1,232 @@
+require 'pandoc-ruby'
+
+module Jekyll
+  module PandocExports
+    
+    Jekyll::Hooks.register :site, :post_write do |site|
+      config = setup_configuration(site)
+      return unless config['enabled']
+      
+      unless validate_dependencies
+        Jekyll.logger.error "Pandoc Exports:", "Missing required dependencies. Please install Pandoc and LaTeX."
+        return
+      end
+      
+      process_collections(site, config)
+    end
+    
+    def self.setup_configuration(site)
+      config = site.config['pandoc_exports'] || {}
+      {
+        'enabled' => true,
+        'output_dir' => '',
+        'collections' => ['pages', 'posts'],
+        'pdf_options' => { 'variable' => 'geometry:margin=1in' },
+        'unicode_cleanup' => true,
+        'inject_downloads' => true,
+        'download_class' => 'pandoc-downloads no-print',
+        'download_style' => 'margin: 20px 0; padding: 15px; background-color: #f8f9fa; border: 1px solid #dee2e6; border-radius: 5px;',
+        'title_cleanup' => [],
+        'image_path_fixes' => []
+      }.merge(config)
+    end
+    
+    def self.validate_dependencies
+      pandoc_available = system('pandoc --version > /dev/null 2>&1')
+      latex_available = system('pdflatex --version > /dev/null 2>&1')
+      
+      unless pandoc_available
+        Jekyll.logger.warn "Pandoc Exports:", "Pandoc not found. Install with: brew install pandoc (macOS) or apt-get install pandoc (Ubuntu)"
+      end
+      
+      unless latex_available
+        Jekyll.logger.warn "Pandoc Exports:", "LaTeX not found. Install with: brew install --cask mactex (macOS) or apt-get install texlive-latex-base (Ubuntu)"
+      end
+      
+      pandoc_available
+    end
+    
+    def self.process_collections(site, config)
+      config['collections'].each do |collection_name|
+        case collection_name
+        when 'pages'
+          site.pages.each { |item| process_item(site, item, config) }
+        when 'posts'
+          site.posts.docs.each { |item| process_item(site, item, config) }
+        else
+          collection = site.collections[collection_name]
+          collection&.docs&.each { |item| process_item(site, item, config) }
+        end
+      end
+    end
+    
+    def self.process_item(site, item, config)
+      return unless item.data['docx'] || item.data['pdf']
+      
+      # Check if file was modified (incremental build)
+      return if skip_unchanged_file?(site, item, config)
+      
+      process_page(site, item, config)
+    end
+    
+    def self.skip_unchanged_file?(site, item, config)
+      return false unless config['incremental']
+      
+      source_file = item.respond_to?(:path) ? item.path : item.relative_path
+      return false unless File.exist?(source_file)
+      
+      filename = get_output_filename(item)
+      output_dir = get_output_directory(site, config)
+      
+      docx_file = File.join(output_dir, "#{filename}.docx")
+      pdf_file = File.join(output_dir, "#{filename}.pdf")
+      
+      source_mtime = File.mtime(source_file)
+      
+      if item.data['docx'] && File.exist?(docx_file)
+        return false if File.mtime(docx_file) < source_mtime
+      end
+      
+      if item.data['pdf'] && File.exist?(pdf_file)
+        return false if File.mtime(pdf_file) < source_mtime
+      end
+      
+      true
+    end
+    
+    def self.get_output_filename(item)
+      if item.respond_to?(:basename)
+        File.basename(item.basename, '.md')
+      else
+        File.basename(item.path, '.md')
+      end
+    end
+    
+    def self.get_output_directory(site, config)
+      if config['output_dir'].empty?
+        site.dest
+      else
+        output_path = File.join(site.dest, config['output_dir'])
+        FileUtils.mkdir_p(output_path) unless Dir.exist?(output_path)
+        output_path
+      end
+    end
+    
+    def self.process_page(site, page, config)
+      html_file = get_html_file_path(site, page)
+      return unless File.exist?(html_file)
+      
+      html_content = File.read(html_file)
+      processed_html = process_html_content(html_content, site, config)
+      filename = get_output_filename(page)
+      output_dir = get_output_directory(site, config)
+      generated_files = []
+      
+      generate_docx(processed_html, filename, output_dir, site, generated_files) if page.data['docx']
+      generate_pdf(processed_html, filename, output_dir, site, generated_files, page, config) if page.data['pdf']
+      
+      if config['inject_downloads'] && generated_files.any?
+        inject_download_links(html_content, generated_files, html_file, config)
+      end
+    end
+    
+    def self.get_html_file_path(site, page)
+      # Handle different Jekyll URL structures
+      if page.url.end_with?('/')
+        File.join(site.dest, page.url, 'index.html')
+      else
+        File.join(site.dest, "#{page.url.gsub('/', '')}.html")
+      end
+    end
+    
+    def self.process_html_content(html_content, site, config)
+      processed = html_content.dup
+      
+      # Apply image path fixes from config
+      config['image_path_fixes'].each do |fix|
+        processed.gsub!(Regexp.new(fix['pattern']), fix['replacement'].gsub('{{site.dest}}', site.dest))
+      end
+      
+      processed
+    end
+    
+    def self.generate_docx(html_content, filename, output_dir, site, generated_files)
+      begin
+        docx_content = PandocRuby.convert(html_content, from: :html, to: :docx)
+        docx_file = File.join(output_dir, "#{filename}.docx")
+        
+        File.open(docx_file, 'wb') { |file| file.write(docx_content) }
+        
+        generated_files << { 
+          type: 'Word Document (.docx)', 
+          url: "#{site.baseurl}/#{filename}.docx" 
+        }
+        Jekyll.logger.info "Pandoc Exports:", "Generated #{filename}.docx"
+      rescue => e
+        Jekyll.logger.error "Pandoc Exports:", "Failed to generate #{filename}.docx: #{e.message}"
+      end
+    end
+    
+    def self.generate_pdf(html_content, filename, output_dir, site, generated_files, page, config)
+      begin
+        pdf_html = html_content.dup
+        
+        # Apply Unicode cleanup if enabled
+        if config['unicode_cleanup']
+          pdf_html = clean_unicode_characters(pdf_html)
+        end
+        
+        # Apply title cleanup patterns from config
+        config['title_cleanup'].each do |pattern|
+          pdf_html.gsub!(Regexp.new(pattern), '')
+        end
+        
+        # Get PDF options from config or page front matter
+        pdf_options = page.data['pdf_options'] || config['pdf_options']
+        
+        pdf_content = PandocRuby.new(pdf_html, from: :html, to: :pdf).convert(pdf_options)
+        pdf_file = File.join(output_dir, "#{filename}.pdf")
+        
+        File.open(pdf_file, 'wb') { |file| file.write(pdf_content) }
+        
+        generated_files << { 
+          type: 'PDF Document (.pdf)', 
+          url: "#{site.baseurl}/#{filename}.pdf" 
+        }
+        Jekyll.logger.info "Pandoc Exports:", "Generated #{filename}.pdf"
+      rescue => e
+        Jekyll.logger.error "Pandoc Exports:", "Failed to generate #{filename}.pdf: #{e.message}"
+      end
+    end
+    
+    def self.clean_unicode_characters(html)
+      # Remove emoji and symbol ranges that cause LaTeX issues
+      html.gsub(/[\u{1F000}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/, '')
+    end
+    
+    def self.inject_download_links(html_content, generated_files, html_file, config)
+      download_html = build_download_html(generated_files, config)
+      
+      # Insert after first heading or at beginning of body
+      if html_content.match(/<h[1-6][^>]*>/)
+        html_content.sub!(/<\/h[1-6]>/, "\\&\n#{download_html}")
+      else
+        html_content.sub!(/<body[^>]*>/, "\\&\n#{download_html}")
+      end
+      
+      File.write(html_file, html_content)
+    end
+    
+    def self.build_download_html(generated_files, config)
+      download_html = "<div class=\"#{config['download_class']}\" style=\"#{config['download_style']}\">" +
+                     "<p><strong>Download Options:</strong></p>" +
+                     "<ul style=\"margin: 5px 0; padding-left: 20px;\">"
+      
+      generated_files.each do |file|
+        download_html += "<li><a href=\"#{file[:url]}\" style=\"color: #007bff; text-decoration: none; font-weight: bold;\">#{file[:type]}</a></li>"
+      end
+      
+      download_html += "</ul></div>"
+    end
+  end
+end

data/lib/jekyll-pandoc-exports/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module PandocExports
+    VERSION = "0.1.4"
+  end
+end

data/lib/jekyll-pandoc-exports.rb

@@ -0,0 +1,2 @@
+require "jekyll-pandoc-exports/version"
+require "jekyll-pandoc-exports/generator"

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-pandoc-exports
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Michael McGarrah
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pandoc-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Automatically generate Word documents and PDFs from Jekyll pages with
+  configurable options, Unicode cleanup, and auto-injected download links.
+email:
+- mcgarrah@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/jekyll-pandoc-exports.rb
+- lib/jekyll-pandoc-exports/generator.rb
+- lib/jekyll-pandoc-exports/version.rb
+homepage: https://github.com/mcgarrah/jekyll-pandoc-exports
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Jekyll plugin to generate DOCX and PDF exports using Pandoc
+test_files: []