booksmith 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38b21a8ba67192f56f7796f1eb76cffe35515449ae9ca7c3a53f20b1aea1d710
+  data.tar.gz: 017caa797d013fcd07cf3d0bbd54501a0e23fd5ed7fa273b7ebb91a19ba54474
+SHA512:
+  metadata.gz: e00830e76a4e9e30679a1681c5f8b82063bd075d5e86c1bf3a4db398f6ef38249b511bdbee279292303379141a9fee03ab4278b5c1da7380cca73fed61ad5b4d
+  data.tar.gz: 8f324bc51843471ade117b2eeb21a9d8453d94b0c658f655a1f7aea64e441363a82e00422bf405d135e9dd21fc5a9eabdc922566e5b067c6f47f5756d347bdd7

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonid Medovyy
+
+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,306 @@
+# Booksmith
+
+[![Gem Version](https://img.shields.io/badge/gem-v1.0.0-crimson.svg?style=flat-square)](https://rubygems.org/gems/booksmith)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg?style=flat-square)](https://www.ruby-lang.org)
+[![Amazon KDP](https://img.shields.io/badge/Amazon%20KDP-Print%20%26%20eBook%20Ready-orange.svg?style=flat-square)](https://kdp.amazon.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE.txt)
+
+> **The production-grade, developer-first publishing engine that transforms Markdown chapters into store-ready Paperback, Hardcover, and Kindle eBook (EPUB) editions.**
+
+---
+
+## Overview
+
+Self-publishing technical guides, fiction, or non-fiction on **Amazon Kindle Direct Publishing (KDP)** usually requires painful manual formatting in Word/InDesign or fragile HTML-to-PDF scripts that fail Amazon's automated interior print inspection.
+
+**Booksmith** solves this with a purpose-built, dual-engine compilation pipeline. Written in Ruby, Booksmith reads clean Markdown and compiles it into:
+
+- **Print-Ready PDFs** configured with Amazon KDP-compliant margins, geometry, vector typography, running headers, and dynamically resolved tables of contents.
+- **Reflowable EPUB 3 eBooks** bundled with embedded typography, validated navigation manifests, and custom callout styling ready for Kindle ingestion.
+
+---
+
+## 🏆 Battle-Tested in Production
+
+Booksmith isn't a theoretical proof-of-concept—it powers live, commercial titles available on Amazon worldwide across **Paperback**, **Hardcover**, and **Kindle eBook** formats:
+
+| Title | Formats Published | Store Link |
+| :--- | :--- | :--- |
+| **Modern Applications of Ninjutsu** | Hardcover • Kindle | [View on Amazon](https://www.amazon.com/dp/B0HNF1T788/) |
+| **Jealousy in the Jungle: Invitation & Rival's Awakening** | Hardcover • Kindle | [View on Amazon](https://www.amazon.com/Jealousy-Jungle-Invitation-Rivals-Awakening/dp/B0DY872FHM/) |
+
+> [!NOTE]
+> Both titles passed Amazon KDP's automated preflight review, interior gutter/margin validation, and reflowable eBook ingest with **zero formatting rejections**.
+
+---
+
+## ✨ Key Features
+
+- **Dual-Target Compilation**: Generate both print-ready PDF and Kindle-compliant EPUB simultaneously with a single CLI command (`booksmith build --format all`).
+- **Two-Pass Dynamic Pagination**: Calculates exact chapter starting pages and table-of-contents page offsets automatically prior to final PDF generation.
+- **Self-Contained Typography**: Bundles Google's **Noto Sans** and **Noto Sans Mono** TrueType font families. No external font dependencies or OS-level font installations required.
+- **Rich Callout Blocks**:
+  - **Standard Callouts**: Automatically styles bold headers into shaded callout blocks.
+  - **Alternate Callouts (`{: .alt_blockquote}`)**: Tinted background containers for sidebars and tips.
+  - **Exercise Callouts (`{: .exercise_blockquote}`)**: Callout cards with customizable asset icons (e.g., timer/clock) and point-level vertical alignment nudges.
+- **Print Layout Control**:
+  - `<!-- subtitle: ... -->` for clean chapter metadata without breaking Markdown linters.
+  - `<!-- PAGE_BREAK -->` comments for manual page control across physical print layouts.
+- **Automated Image Pipeline**: Parses inline Markdown sizing attributes (`"width=350 top=10 bottom=10"`) and rasterizes transparent PNG backgrounds via ImageMagick to prevent black-box PDF rendering artifacts.
+
+---
+
+## 🏗️ Architecture & Engineering Highlights
+
+Booksmith was engineered with a modular, extensible architecture that separates AST parsing, layout geometry calculations, and format-specific document packaging.
+
+```mermaid
+flowchart TD
+    MD["Markdown Chapters (chapters/*.md)"] --> AST["Kramdown AST Parser & Normalizer"]
+    CFG["Configuration (config/book.yml)"] --> AST
+
+    subgraph PDF_Pipeline ["Print Engine: Prawn (2-Pass Layout)"]
+        AST --> P1["Pass 1: Render Dry-Run & Measure Offsets"]
+        P1 --> TOC["Compute TOC Height & Page Shift Offset"]
+        TOC --> P2["Pass 2: Final Vector Rendering & Running Pagination"]
+        P2 --> PDF_OUT["book.pdf (Paperback & Hardcover Ready)"]
+    end
+
+    subgraph EPUB_Pipeline ["eBook Engine: GEPUB (EPUB 3 / XHTML)"]
+        AST --> XGEN["XHTML 1.1 Document Generator & CSS Styler"]
+        XGEN --> SPN["Embed Fonts, Assets & Build EPUB Spine"]
+        SPN --> EPUB_OUT["book.epub (Kindle KDP Ready)"]
+    end
+```
+
+### Engineering Design Highlights
+
+#### 1. Two-Pass PDF Pagination & TOC Resolution
+
+Generating a table of contents in print documents presents a circular dependency: adding TOC entries can push chapter pages down, altering the page numbers that the TOC itself displays. Booksmith resolves this with a deterministic two-pass algorithm:
+
+1. **Pass 1 (Measurement)**: Traverses the Kramdown AST in an in-memory Prawn buffer to compute exact chapter heights, section boundaries, and TOC page space.
+2. **Pass 2 (Synthesis)**: Applies the computed TOC page offset, injects the generated Table of Contents, formats running page numbers (`page_content_bottom_gap`), and writes the final vector PDF.
+
+#### 2. Vector Typography & Geometry Engine
+
+Instead of relying on web-view wrappers or headless browsers, Booksmith renders directly to PDF primitives using `Prawn`. Text leading, bullet indentations (`list_bullet_indent`, `list_marker_gap`), and callout paddings are calculated in points, producing crisp vector type that meets high-resolution commercial print standards (300+ DPI).
+
+#### 3. Dual-Format AST Translation
+
+Booksmith normalizes Markdown elements into an intermediate AST via Kramdown, then branches execution:
+
+- **PDF Converter** (`Booksmith::PDFConverter`): Translates elements into low-level Prawn cursor calls, handling bounding boxes, font switching, and multi-column icon callouts.
+- **EPUB Generator** (`Booksmith::EpubGenerator`): Serializes nodes into strict XHTML, injects embedded CSS, registers the TrueType fonts in the OPF manifest, and packages the complete EPUB 3 archive via GEPUB.
+
+#### 4. Automated Image Pre-processing & Alpha Flattening
+
+PDF renderers and commercial print presses frequently misrender PNG alpha transparency as opaque black blocks. Booksmith reads configuration-driven background colors (`image_flatten_bg_color`) and utilizes ImageMagick to composite transparent images against the target page tone before embedding.
+
+---
+
+## 🚀 Quickstart
+
+### 1. Installation
+
+Install Booksmith via RubyGems:
+
+```sh
+gem install booksmith
+```
+
+Or add it to your project's `Gemfile`:
+
+```ruby
+gem 'booksmith', '~> 1.0'
+```
+
+### 2. Initialize a Project
+
+Create a new book directory and initialize the scaffolding:
+
+```sh
+mkdir my-masterpiece
+cd my-masterpiece
+booksmith init
+```
+
+This generates the standard project structure:
+
+```
+my-masterpiece/
+├── assets/
+│   └── clock.png                  # Sample exercise callout icon
+├── chapters/
+│   └── 01_introduction.md         # Starter chapter template
+└── config/
+    └── book.yml                   # Master typography, metadata & layout config
+```
+
+### 3. Build Your Book
+
+Compile your chapters into your target formats:
+
+```sh
+# Generate Paperback/Hardcover PDF (default: book.pdf)
+booksmith build
+
+# Generate Kindle-ready EPUB (book.epub)
+booksmith build --epub
+
+# Generate both formats simultaneously
+booksmith build --format all
+
+# Build PDF without cover page
+booksmith build --no-cover
+```
+
+### 4. Inspect Registered Fonts
+
+```sh
+booksmith fonts
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+All book layout options, metadata, and typography parameters are managed in `config/book.yml`:
+
+```yaml
+---
+# Book Metadata
+:title: "Modern Applications of Ninjutsu"
+:author: "Authored by Leonid Medovyy"
+
+# Font Typography
+:title_font: "Noto Sans Mono"
+:author_font: "Noto Sans Mono"
+:header_font: "Noto Sans"
+:subtitle_font: "Noto Sans Mono"
+:body_font: "Noto Sans"
+
+# Print & Page Geometry
+:blank_page_after_cover: true
+:table_of_contents: true
+:font_size: 10.0
+:line_height: 1.5
+:page_numbers: true
+:page_number_font_size: 9
+:page_content_bottom_gap: 30
+
+# Header Sizing (Points)
+:title_font_size: 24
+:author_font_size: 18
+:h1_font_size: 20
+:h2_font_size: 18
+:h3_font_size: 14
+:h4_font_size: 12
+
+# Callout Boxes & Blockquotes
+:blockquote_bg_color: "EEEEEE"
+:blockquote_padding: 12
+:blockquote_margin_top: 10
+:blockquote_margin_bottom: 10
+
+# Exercise Callout with Custom Icon
+:exercise_blockquote_bg_color: "EEF3FF"
+:exercise_blockquote_image: "assets/clock.png"
+:exercise_blockquote_image_width: 18
+:exercise_blockquote_image_height: 18
+:exercise_blockquote_image_voffset: -2
+```
+
+---
+
+## ✍️ Markdown Authoring Guide
+
+Booksmith supports full GitHub Flavored Markdown with custom layout enhancements:
+
+### Chapter Titles & Subtitles
+
+Use standard `#` for chapter titles, followed immediately by an invisible subtitle comment:
+
+```markdown
+# CHAPTER I
+<!-- subtitle: GETTING STARTED WITH BOOKSMITH -->
+
+Chapter opening text starts here...
+```
+
+### Manual Page Breaks
+
+Insert a clean page break anywhere in your manuscript without adding visible artifacts in Markdown viewers:
+
+```markdown
+<!-- PAGE_BREAK -->
+```
+
+### Styled Callout Boxes
+
+```markdown
+> **Pro Tip**
+>
+> Standard callouts automatically elevate bold first lines into header titles.
+
+> **Sidebar Note**
+>
+> Alternate shaded callout box for supplementary commentary.
+{: .alt_blockquote}
+
+> Hands-On Challenge
+>
+> Exercise callout displaying the configured icon alongside the prompt:
+> - Define the core thesis of your publication
+> - Configure print trim sizes in book.yml
+{: .exercise_blockquote}
+```
+
+### Sized & Centered Images
+
+Specify dimensions and vertical padding directly in image Markdown:
+
+```markdown
+![System Architecture](assets/architecture.png "width=350 top=15 bottom=15")
+```
+
+---
+
+## 📊 Feature Comparison
+
+| Feature | Booksmith | Pandoc / LaTeX | Word / InDesign |
+| :--- | :---: | :---: | :---: |
+| **KDP Print-Ready Out of the Box** | ✅ Yes | ⚠️ Requires Config | ❌ Manual Formatting |
+| **Simultaneous PDF & EPUB Output** | ✅ Yes | ⚠️ Separate Pipelines | ❌ Separate Exports |
+| **Dynamic 2-Pass TOC Resolution** | ✅ Built-in | ⚠️ Complex LaTeX Runs | ❌ Manual TOC Updates |
+| **Zero External Font Dependencies** | ✅ Bundled TTF | ❌ System Fonts | ❌ System Fonts |
+| **Markdown Linter Safe Comments** | ✅ Yes (`<!-- -->`) | ❌ LaTeX Injections | ❌ N/A |
+| **Transparent PNG Flattening** | ✅ Automated | ❌ Manual Preprocessing | ⚠️ Manual Flattening |
+
+---
+
+## 🛠️ CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `booksmith init` | Scaffolds a new book workspace with directories, default assets, sample chapter, and `book.yml`. |
+| `booksmith build` | Builds `book.pdf` with Amazon KDP print specifications. |
+| `booksmith build --epub` | Builds `book.epub` with validated navigation and embedded typography. |
+| `booksmith build --format all` | Compiles both PDF and EPUB in a single pass. |
+| `booksmith build --no-cover` | Omits the title/cover page from generation. |
+| `booksmith fonts` | Lists all registered font families available for document rendering. |
+
+---
+
+## 👤 Author
+
+Crafted by **Leonid Medovyy** ([@leouofa](https://github.com/leouofa)).
+
+- **GitHub**: [@leouofa](https://github.com/leouofa)
+- **Gem**: [rubygems.org/gems/booksmith](https://rubygems.org/gems/booksmith)
+
+---
+
+## 📄 License
+
+This project is open-source under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/bin/booksmith

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'booksmith'
+Booksmith::CLI.run!

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'booksmith'
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/booksmith.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'booksmith/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'booksmith'
+  spec.version       = Booksmith::VERSION
+  spec.authors       = ['Leonid Medovyy']
+  spec.email         = ['leonid@storypro.io']
+
+  spec.summary       = 'A flexible Markdown-to-PDF and EPUB book publishing tool'
+  spec.description   = 'Converts Markdown chapters into a styled PDF or EPUB book using Prawn, GEPUB, and Kramdown.'
+  spec.homepage      = 'https://github.com/leouofa/booksmith'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{bin,lib}/**/*').select { |f| File.file?(f) } +
+      %w[LICENSE.txt README.md Rakefile Gemfile booksmith.gemspec].select { |f| File.file?(f) }
+  end
+  spec.bindir        = 'bin'
+  spec.executables   = ['booksmith']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'commander', '>= 4.6'
+  spec.add_dependency 'gepub', '>= 1.0'
+  spec.add_dependency 'kramdown', '>= 2.4'
+  spec.add_dependency 'ostruct'
+  spec.add_dependency 'prawn', '>= 2.4'
+
+  spec.add_development_dependency 'bundler', '>= 2.0'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
+end

data/lib/booksmith/blockquotes.rb

@@ -0,0 +1,228 @@
+module Booksmith
+  module Blockquotes
+    private
+
+    def render_blockquote(el, style_name)
+      bg_color = blockquote_style_value(style_name, :bg_color, 'EEEEEE')
+      padding_left = blockquote_padding(style_name, :left)
+      padding_right = blockquote_padding(style_name, :right)
+      padding_top = blockquote_padding(style_name, :top)
+      padding_bottom = blockquote_padding(style_name, :bottom)
+      margin_top = blockquote_style_value(style_name, :margin_top, 10).to_f
+      margin_bot = blockquote_style_value(style_name, :margin_bottom, 10).to_f
+      content_width = @pdf.bounds.width - padding_left - padding_right
+      header_el, body_els = split_blockquote_children(el)
+
+      @pdf.move_down margin_top
+
+      box_height = measure_blockquote_height(el, content_width, style_name) + padding_top + padding_bottom
+
+      saved = @pdf.fill_color
+      @pdf.fill_color bg_color
+      @pdf.fill_rectangle([@pdf.bounds.left, @pdf.cursor], @pdf.bounds.width, box_height)
+      @pdf.fill_color saved
+
+      @pdf.move_down padding_top
+      with_image_flatten_bg(blockquote_image_flatten_color(style_name)) do
+        @pdf.indent(padding_left, padding_right) do
+          render_blockquote_title_row(header_el, style_name) if header_el
+          body_els.each { |child| convert_element(child) }
+        end
+      end
+      @pdf.move_down padding_bottom
+      @pdf.move_down margin_bot
+    end
+
+    def render_exercise_blockquote(el)
+      bg_color   = blockquote_style_value(:exercise_blockquote, :bg_color, 'EEF3FF')
+      padding_left   = blockquote_padding(:exercise_blockquote, :left)
+      padding_right  = blockquote_padding(:exercise_blockquote, :right)
+      padding_top    = blockquote_padding(:exercise_blockquote, :top)
+      padding_bottom = blockquote_padding(:exercise_blockquote, :bottom)
+      margin_top = blockquote_style_value(:exercise_blockquote, :margin_top, 12).to_f
+      margin_bot = blockquote_style_value(:exercise_blockquote, :margin_bottom, 12).to_f
+      content_width = @pdf.bounds.width - padding_left - padding_right
+
+      header_el, body_els = split_exercise_children(el)
+
+      @pdf.move_down margin_top
+
+      box_height = measure_exercise_height(content_width, header_el, body_els) + padding_top + padding_bottom
+      top_cursor = @pdf.cursor
+
+      saved = @pdf.fill_color
+      @pdf.fill_color bg_color
+      @pdf.fill_rectangle([@pdf.bounds.left, top_cursor], @pdf.bounds.width, box_height)
+      @pdf.fill_color saved
+
+      @pdf.move_down padding_top
+      with_image_flatten_bg(blockquote_image_flatten_color(:exercise_blockquote)) do
+        @pdf.indent(padding_left, padding_right) do
+          render_exercise_title_row(header_el)
+          body_els.each { |child| convert_element(child) }
+        end
+      end
+      @pdf.move_down padding_bottom
+      @pdf.move_down margin_bot
+    end
+
+    def alt_blockquote?(element)
+      classes = element.attr.fetch('class', '').split
+      classes.include?('alt_blockquote')
+    end
+
+    def exercise_blockquote?(element)
+      element.attr.fetch('class', '').split.include?('exercise_blockquote')
+    end
+
+    def blockquote_header_paragraph?(element)
+      return false unless element&.type == :p
+
+      inline = element.children.reject { |c| c.type == :blank || (c.type == :text && c.value.strip.empty?) }
+      inline.length == 1 && inline.first.type == :strong
+    end
+
+    def split_blockquote_children(el)
+      children = el.children.reject { |c| c.type == :blank }
+      return [nil, children] if children.empty?
+      return [children.first, children.drop(1)] if blockquote_header_paragraph?(children.first)
+
+      [nil, children]
+    end
+
+    def split_exercise_children(el)
+      children = el.children.reject { |c| c.type == :blank }
+      [children.first, children.drop(1)]
+    end
+
+    def blockquote_style_value(style_name, setting, default)
+      key = :"#{style_name}_#{setting}"
+      fallback_key = :"blockquote_#{setting}"
+
+      return @config[key] if @config.key?(key)
+      return @config[fallback_key] if style_name != :blockquote && @config.key?(fallback_key)
+
+      default
+    end
+
+    def blockquote_padding(style_name, side)
+      per_side_key = :"#{style_name}_padding_#{side}"
+      return @config[per_side_key].to_f if @config.key?(per_side_key)
+
+      if style_name != :blockquote
+        fallback_per_side = :"blockquote_padding_#{side}"
+        return @config[fallback_per_side].to_f if @config.key?(fallback_per_side)
+      end
+
+      default_padding = style_name == :exercise_blockquote ? 14 : 12
+      blockquote_style_value(style_name, :padding, default_padding).to_f
+    end
+
+    def blockquote_header_font_size(style_name)
+      blockquote_style_value(style_name, :header_font_size, @config[:font_size] + 4).to_f
+    end
+
+    def exercise_header_font_size
+      blockquote_header_font_size(:exercise_blockquote)
+    end
+
+    def exercise_title_row_height(img_height, title_size, header_text, title_width)
+      header_height = @pdf.height_of(header_text, size: title_size, style: :bold, width: title_width)
+      [img_height, header_height].max
+    end
+
+    def render_blockquote_title_row(header_el, style_name)
+      header_text = plain_text(header_el)
+      title_size = blockquote_header_font_size(style_name)
+      header_gap = blockquote_style_value(style_name, :header_gap, 6).to_f
+      row_height = @pdf.height_of(header_text, size: title_size, style: :bold, width: @pdf.bounds.width)
+
+      @pdf.text_box(
+        header_text,
+        at: [@pdf.bounds.left, @pdf.cursor],
+        width: @pdf.bounds.width,
+        height: row_height,
+        size: title_size,
+        style: :bold,
+        valign: :top
+      )
+      @pdf.move_down row_height + header_gap
+    end
+
+    def render_exercise_title_row(header_el)
+      header_text = plain_text(header_el)
+      title_size = exercise_header_font_size
+      img_width = blockquote_style_value(:exercise_blockquote, :image_width, 28).to_f
+      img_height = blockquote_style_value(:exercise_blockquote, :image_height, img_width).to_f
+      img_gap = blockquote_style_value(:exercise_blockquote, :image_gap, 8).to_f
+      img_voffset = blockquote_style_value(:exercise_blockquote, :image_voffset, 0).to_f
+      header_gap = blockquote_style_value(:exercise_blockquote, :header_gap, 6).to_f
+      title_width = [@pdf.bounds.width - img_width - img_gap, 1].max
+      row_height = exercise_title_row_height(img_height, title_size, header_text, title_width)
+
+      @pdf.bounding_box([@pdf.bounds.left, @pdf.cursor], width: @pdf.bounds.width, height: row_height) do
+        image_path = exercise_image_path
+        if image_path
+          @pdf.bounding_box([0, row_height + img_voffset], width: img_width, height: row_height) do
+            @pdf.image(image_path, fit: [img_width, img_height], position: :center, vposition: :center)
+          end
+        end
+
+        @pdf.text_box(
+          header_text,
+          at: [img_width + img_gap, row_height],
+          width: title_width,
+          height: row_height,
+          size: title_size,
+          style: :bold,
+          valign: :center
+        )
+      end
+
+      @pdf.move_down header_gap
+    end
+
+    def exercise_image_path
+      path = @config.fetch(:exercise_blockquote_image, 'assets/question_mark.png')
+      expanded = File.expand_path(path, Dir.pwd)
+      return nil unless File.exist?(expanded)
+
+      bg_color = blockquote_image_flatten_color(:exercise_blockquote)
+      prepare_png_path(expanded, background_color: bg_color)
+    end
+
+    def measure_blockquote_height(el, content_width, style_name = :blockquote)
+      header_el, body_els = split_blockquote_children(el)
+      scratch = create_scratch_document(content_width)
+      flatten_bg = blockquote_image_flatten_color(style_name)
+      converter = PDFConverter.new(scratch, @config, image_flatten_bg: flatten_bg)
+      start_y = scratch.cursor
+      if header_el
+        converter.send(:render_blockquote_title_row, header_el, style_name)
+        body_els.each { |child| converter.send(:convert_element, child) }
+      else
+        body_els.each { |child| converter.send(:convert_element, child) }
+      end
+      [start_y - scratch.cursor, 0].max
+    end
+
+    def measure_exercise_height(content_width, header_el, body_els)
+      scratch = create_scratch_document(content_width)
+      flatten_bg = blockquote_image_flatten_color(:exercise_blockquote)
+      converter = PDFConverter.new(scratch, @config, image_flatten_bg: flatten_bg)
+      start_y = scratch.cursor
+      converter.send(:render_exercise_title_row, header_el)
+      body_els.each { |child| converter.send(:convert_element, child) }
+      [start_y - scratch.cursor, 0].max
+    end
+
+    def create_scratch_document(content_width)
+      scratch = Prawn::Document.new(
+        page_size: [content_width + 2, 5000], margin: [0, 1, 0, 1]
+      )
+      FontPaths.register(scratch)
+      scratch.font(@config.fetch(:body_font, 'Noto Sans'))
+      scratch
+    end
+  end
+end