jekyll-pandoc-exports 0.1.14 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca2a0537fbb9140f794e1a067ea8c5d11158d67a6c113f9b05c0b49977686f91
-  data.tar.gz: 242fa714998209a32555dfaeea645bdf9cc70f64105d088940215346c576859c
+  metadata.gz: 70da42a9e14e74c755a0e9cda4cc17a5fbe348075214d1d1820f3a06d40da60b
+  data.tar.gz: a862b3fab61784e2d37501f1e73982ab6e68495a6c90f7fadebd352abcaa7a5c
 SHA512:
-  metadata.gz: ecd9468193ec01c865b2738524ec3a3831e26cf23175fe4ee5ff4112366a8042717065c8e8e8e41f95ae8275ffcf0db710b2be2b9994a571be8078d4deb88182
-  data.tar.gz: e5e1af055ee84786049f38bb4d7d78666ff3c94c6a54f067318ced7ae25e3e3a2bf24ad640856e15d92757780cdb495279b42494d7e38839cf36dd640e6bf9b1
+  metadata.gz: 402bf541eaa772936ef7b2cc8691f557020c1d830a0bfeedf7d5b798ad5ffc6a7c2679fe4643115195651743d80ef0cb42b5064ee1f3594cec4ca172ce970baa
+  data.tar.gz: 07e74c42a95154d183431db6164546aa589e09fc71d28f77f37315dbf8e32175c84b84a324f77607ef83e623999a9c8168785858adc11a587478596e6622eade

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-06
+
+### Added
+- `jekyll export` command — generate PDF/DOCX without a full site build
+- `--format` flag: select `pdf`, `docx`, or `both` output
+- `--target` flag: export a specific page by filename
+- `--dry-run` flag: print the Pandoc command without executing
+- `--validate` flag: check `_data/data.yml` schema before export
+- `--output` flag: override the output directory
+- Pre-export YAML schema validation (checks required sections, fields, structure)
+- `export_filename` front matter support: custom output filenames (e.g., `McGarrah-Resume` instead of `print`)
+- `build_download_url` helper for correct download link generation with output_dir
+- Test suite for the export command (10 tests, 15 assertions)
+
+### Changed
+- Version bump to 0.2.0 (new feature: Jekyll Command integration)
+- Minimum Ruby version raised from 3.0 to 3.2 (3.0 and 3.1 are EOL)
+- CI matrix updated to Ruby 3.2, 3.3, 3.4 (dropped EOL 3.0, 3.1; added current 3.4)
+
 ## [0.1.14] - 2025-06-14
 
 ### Fixed

data/README.md

@@ -17,6 +17,13 @@ A Jekyll plugin that automatically generates DOCX and PDF exports of your pages
 
 ## Installation
 
+### Requirements
+
+- **Ruby** >= 3.2.0
+- **Jekyll** >= 4.3.2 (earlier versions crash on Ruby 3.2+ due to Liquid's removed `tainted?` method)
+- **Pandoc** (for document conversion)
+- **LaTeX** (for PDF generation)
+
 ### 1. Install Dependencies
 
 First, install Pandoc and LaTeX (for PDF generation):
@@ -193,7 +200,48 @@ When `inject_downloads` is enabled, the plugin automatically adds download links
 
 ## CLI Usage
 
-The plugin includes a command-line tool for standalone conversions:
+The plugin provides two command-line interfaces:
+
+### Jekyll Export Command (Recommended)
+
+*Added in v0.2.0* — Runs within your Jekyll site context, reads `_config.yml`:
+
+```bash
+# Build site first, then export without rebuilding
+bundle exec jekyll build
+bundle exec jekyll export
+
+# Export PDF only
+bundle exec jekyll export --format pdf
+
+# Export a specific page
+bundle exec jekyll export --target print
+
+# See what Pandoc would run (debug LaTeX issues)
+bundle exec jekyll export --dry-run
+
+# Validate _data/data.yml schema before export
+bundle exec jekyll export --validate
+
+# Custom output directory
+bundle exec jekyll export --output ~/Downloads
+```
+
+#### Export Command Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--format FORMAT` | Output: `pdf`, `docx`, `both` | `both` |
+| `--target TARGET` | Export specific page by filename | All configured pages |
+| `--dry-run` | Print Pandoc command without executing | `false` |
+| `--validate` | Validate `_data/data.yml` schema first | `false` |
+| `--output DIR` | Override output directory | From `_config.yml` |
+| `--source DIR` | Source directory | `.` |
+| `--config FILE` | Configuration file | `_config.yml` |
+
+### Standalone CLI Tool
+
+For converting individual HTML files outside of Jekyll:
 
 ```bash
 # Convert single HTML file to both formats

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

@@ -0,0 +1,316 @@
+require 'jekyll'
+
+module Jekyll
+  module PandocExports
+    class Command < Jekyll::Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:export) do |c|
+            c.syntax "export [options]"
+            c.description "Generate PDF/DOCX exports without a full site build"
+
+            c.option 'format', '--format FORMAT', 'Output format: pdf, docx, both (default: both)'
+            c.option 'target', '--target TARGET', 'Target page to export by filename (default: all configured pages)'
+            c.option 'dry_run', '--dry-run', 'Print the Pandoc command without executing'
+            c.option 'validate', '--validate', 'Validate _data/data.yml schema before export'
+            c.option 'output', '-o', '--output DIR', 'Override output directory'
+            c.option 'source', '-s', '--source DIR', 'Source directory (default: .)'
+            c.option 'config', '--config FILE', 'Configuration file (default: _config.yml)'
+
+            c.action do |args, options|
+              ExportRunner.new(args, options).run
+            end
+          end
+        end
+      end
+    end
+
+    class ExportRunner
+      def initialize(args, options)
+        @args = args
+        @options = options
+        @format = (options['format'] || 'both').downcase
+        @target = options['target']
+        @dry_run = options['dry_run'] || false
+        @validate = options['validate'] || false
+        @output_dir = options['output']
+        @source = options['source'] || '.'
+        @config_file = options['config'] || '_config.yml'
+      end
+
+      def run
+        # Ensure logger shows info-level output for CLI feedback
+        Jekyll.logger.adjust_verbosity(verbose: true)
+
+        validate_format!
+        validate_schema! if @validate
+
+        config = load_site_config
+        export_config = PandocExports.setup_configuration(mock_site(config))
+
+        unless PandocExports.validate_dependencies
+          Jekyll.logger.error "Export:", "Missing required dependencies."
+          return
+        end
+
+        html_files = find_export_targets(config, export_config)
+
+        if html_files.empty?
+          Jekyll.logger.warn "Export:", "No export targets found. Run 'jekyll build' first, or check that pages have pdf/docx front matter."
+          return
+        end
+
+        html_files.each do |target|
+          export_file(target, config, export_config)
+        end
+
+        Jekyll.logger.info "Export:", "Complete."
+      end
+
+      private
+
+      def validate_format!
+        unless %w[pdf docx both].include?(@format)
+          Jekyll.logger.error "Export:", "Invalid format '#{@format}'. Use: pdf, docx, both"
+          exit 1
+        end
+      end
+
+      def validate_schema!
+        Jekyll.logger.info "Export:", "Validating _data/data.yml..."
+
+        data_file = File.join(@source, '_data', 'data.yml')
+        unless File.exist?(data_file)
+          Jekyll.logger.warn "Export:", "No _data/data.yml found — skipping validation."
+          return
+        end
+
+        begin
+          require 'yaml'
+          require 'date'
+          data = YAML.load_file(data_file, permitted_classes: [Date])
+
+          errors = []
+
+          # Check required top-level keys
+          %w[sidebar career-profile education experiences].each do |key|
+            errors << "Missing required section: '#{key}'" unless data.key?(key)
+          end
+
+          # Check sidebar required fields
+          if data['sidebar']
+            %w[name tagline email].each do |field|
+              errors << "Missing sidebar.#{field}" unless data['sidebar'][field]
+            end
+          end
+
+          # Check experiences structure
+          if data['experiences'] && data['experiences']['info']
+            data['experiences']['info'].each_with_index do |exp, i|
+              errors << "Experience ##{i + 1} missing 'role'" unless exp['role']
+              errors << "Experience ##{i + 1} missing 'company'" unless exp['company']
+              errors << "Experience ##{i + 1} missing 'time'" unless exp['time']
+            end
+          end
+
+          # Check education structure
+          if data['education'] && data['education']['info']
+            data['education']['info'].each_with_index do |edu, i|
+              errors << "Education ##{i + 1} missing 'degree'" unless edu['degree']
+              errors << "Education ##{i + 1} missing 'university'" unless edu['university']
+            end
+          end
+
+          if errors.any?
+            Jekyll.logger.error "Export:", "Schema validation failed:"
+            errors.each { |e| Jekyll.logger.error "  ", e }
+            exit 1
+          else
+            Jekyll.logger.info "Export:", "Schema validation passed ✓"
+          end
+        rescue Psych::SyntaxError => e
+          Jekyll.logger.error "Export:", "YAML syntax error: #{e.message}"
+          exit 1
+        end
+      end
+
+      def load_site_config
+        config_path = File.join(@source, @config_file)
+        unless File.exist?(config_path)
+          Jekyll.logger.error "Export:", "Config file not found: #{config_path}"
+          exit 1
+        end
+
+        Jekyll.configuration({
+          'source' => @source,
+          'quiet' => false
+        })
+      end
+
+      def mock_site(config)
+        site = Object.new
+        site.define_singleton_method(:config) { config }
+        site.define_singleton_method(:dest) { config['destination'] }
+        site.define_singleton_method(:baseurl) { config['baseurl'] || '' }
+        site
+      end
+
+      def find_export_targets(config, export_config)
+        dest = config['destination']
+        unless Dir.exist?(dest)
+          Jekyll.logger.error "Export:", "Site destination '#{dest}' not found. Run 'jekyll build' first."
+          exit 1
+        end
+
+        targets = []
+
+        # Scan for HTML files with pdf/docx front matter markers
+        # The simplest approach: look for files that the generator would process
+        # by checking the source pages for front matter
+        source = config['source']
+
+        Dir.glob(File.join(source, '**', '*.html')).each do |source_file|
+          content = File.read(source_file)
+          next unless content.start_with?('---')
+
+          # Parse front matter
+          if content =~ /\A---\s*\n(.*?)\n---/m
+            begin
+              front_matter = YAML.safe_load($1) || {}
+            rescue
+              next
+            end
+
+            next unless front_matter['pdf'] || front_matter['docx']
+
+            # Determine the output HTML path
+            filename = File.basename(source_file, '.html')
+
+            # Filter by target if specified
+            if @target
+              next unless filename == @target || source_file.include?(@target)
+            end
+
+            # Find the built HTML file
+            permalink = front_matter['permalink']
+            if permalink
+              html_path = File.join(dest, permalink, 'index.html')
+              html_path = File.join(dest, "#{permalink.sub(/^\//, '')}.html") unless File.exist?(html_path)
+              # Try without trailing slash
+              html_path = File.join(dest, permalink, 'index.html') unless File.exist?(html_path)
+              # Direct path
+              html_path = File.join(dest, "#{permalink.sub(/^\//, '')}index.html") unless File.exist?(html_path)
+            else
+              html_path = File.join(dest, "#{filename}.html")
+              html_path = File.join(dest, filename, 'index.html') unless File.exist?(html_path)
+            end
+
+            if File.exist?(html_path)
+              targets << {
+                filename: filename,
+                html_path: html_path,
+                front_matter: front_matter
+              }
+            else
+              Jekyll.logger.warn "Export:", "Built HTML not found for #{source_file} (expected: #{html_path})"
+            end
+          end
+        end
+
+        targets
+      end
+
+      def export_file(target, config, export_config)
+        filename = target[:front_matter]['export_filename'] || target[:filename]
+        html_path = target[:html_path]
+        front_matter = target[:front_matter]
+
+        html_content = File.read(html_path)
+        site = mock_site(config)
+        processed_html = PandocExports.process_html_content(html_content, site, export_config)
+
+        output_dir = determine_output_dir(config, export_config)
+        FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
+
+        generated_files = []
+
+        if should_generate_docx?(front_matter)
+          if @dry_run
+            print_dry_run(:docx, processed_html, filename, output_dir, export_config)
+          else
+            PandocExports.generate_docx(processed_html, filename, output_dir, site, generated_files, export_config)
+          end
+        end
+
+        if should_generate_pdf?(front_matter)
+          if @dry_run
+            print_dry_run(:pdf, processed_html, filename, output_dir, export_config)
+          else
+            mock_page = Object.new
+            mock_page.define_singleton_method(:data) { front_matter }
+            PandocExports.generate_pdf(processed_html, filename, output_dir, site, generated_files, mock_page, export_config)
+          end
+        end
+      end
+
+      def determine_output_dir(config, export_config)
+        if @output_dir
+          File.expand_path(@output_dir)
+        elsif export_config['output_dir'] && !export_config['output_dir'].empty?
+          File.join(config['destination'], export_config['output_dir'])
+        else
+          config['destination']
+        end
+      end
+
+      def should_generate_docx?(front_matter)
+        return false unless front_matter['docx']
+        %w[docx both].include?(@format)
+      end
+
+      def should_generate_pdf?(front_matter)
+        return false unless front_matter['pdf']
+        %w[pdf both].include?(@format)
+      end
+
+      def print_dry_run(format, html_content, filename, output_dir, config)
+        output_file = File.join(output_dir, "#{filename}.#{format}")
+
+        # Build the equivalent pandoc command
+        pandoc_args = ["pandoc"]
+        pandoc_args << "--from=html"
+        pandoc_args << "--to=#{format == :pdf ? 'pdf' : 'docx'}"
+        pandoc_args << "--output=#{output_file}"
+
+        if format == :pdf
+          pdf_options = config['pdf_options'] || {}
+          pdf_options.each do |key, value|
+            pandoc_args << "--#{key}=#{value}"
+          end
+
+          pandoc_options = config['pandoc_options'] || {}
+          pandoc_options.each do |key, value|
+            pandoc_args << "--#{key}=#{value}"
+          end
+        end
+
+        pandoc_args << "< [stdin: #{html_content.bytesize} bytes HTML]"
+
+        Jekyll.logger.info "Export [DRY RUN]:", pandoc_args.join(" ")
+        Jekyll.logger.info "  Input:", "#{html_content.bytesize} bytes of processed HTML"
+        Jekyll.logger.info "  Output:", output_file
+
+        if config['unicode_cleanup'] && format == :pdf
+          Jekyll.logger.info "  Unicode:", "cleanup enabled (emoji/symbols stripped)"
+        end
+
+        cleanup_count = (config['title_cleanup'] || []).length
+        if cleanup_count > 0
+          Jekyll.logger.info "  Cleanup:", "#{cleanup_count} title_cleanup patterns applied"
+        else
+          Jekyll.logger.info "  Cleanup:", "none (clean HTML input)"
+        end
+      end
+    end
+  end
+end

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

@@ -119,6 +119,11 @@ module Jekyll
     end
     
     def self.get_output_filename(item)
+      # Support custom export filenames via front matter
+      if item.respond_to?(:data) && item.data['export_filename']
+        return item.data['export_filename']
+      end
+
       if item.respond_to?(:basename)
         File.basename(item.basename, '.md')
       else
@@ -230,7 +235,7 @@ module Jekyll
         
         generated_files << { 
           type: 'Word Document (.docx)', 
-          url: "#{site.baseurl}/#{filename}.docx" 
+          url: build_download_url(site, config, filename, 'docx')
         }
         @stats&.record_conversion_success(:docx)
         log_message(config, "Generated #{filename}.docx")
@@ -272,7 +277,7 @@ module Jekyll
         
         generated_files << { 
           type: 'PDF Document (.pdf)', 
-          url: "#{site.baseurl}/#{filename}.pdf" 
+          url: build_download_url(site, config, filename, 'pdf')
         }
         @stats&.record_conversion_success(:pdf)
         log_message(config, "Generated #{filename}.pdf")
@@ -320,6 +325,15 @@ module Jekyll
         Jekyll.logger.info "Pandoc Exports:", message
       end
     end
+
+    def self.build_download_url(site, config, filename, extension)
+      output_dir = config['output_dir'] || ''
+      if output_dir.empty?
+        "#{site.baseurl}/#{filename}.#{extension}"
+      else
+        "#{site.baseurl}/#{output_dir}/#{filename}.#{extension}"
+      end
+    end
     
     def self.log_error(config, message)
       Jekyll.logger.error "Pandoc Exports:", message

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

@@ -1,5 +1,5 @@
 module Jekyll
   module PandocExports
-    VERSION = '0.1.14'
+    VERSION = '0.2.0'
   end
 end

data/lib/jekyll-pandoc-exports.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-pandoc-exports
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael McGarrah
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.3.2
 - !ruby/object:Gem::Dependency
   name: pandoc-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -96,6 +96,7 @@ files:
 - bin/release
 - bin/reset-dev
 - lib/jekyll-pandoc-exports.rb
+- lib/jekyll-pandoc-exports/command.rb
 - lib/jekyll-pandoc-exports/generator.rb
 - lib/jekyll-pandoc-exports/hooks.rb
 - lib/jekyll-pandoc-exports/statistics.rb
@@ -118,7 +119,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="