Notare/README.md

Ezdoc

A Ruby gem for creating docx files with a simple DSL

Installation

Add this line to your application's Gemfile:

gem 'ezdoc'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ezdoc

Usage

Basic Example

require 'ezdoc'

Ezdoc::Document.create("output.docx") do |doc|
  doc.p "Hello World"
end

Paragraphs

Ezdoc::Document.create("output.docx") do |doc|
  # Simple paragraph
  doc.p "This is a paragraph."

  # Paragraph with multiple text runs
  doc.p do
    doc.text "First part. "
    doc.text "Second part."
  end
end

Text Formatting

Formatting uses nested blocks. Nesting combines formatting styles.

Ezdoc::Document.create("output.docx") do |doc|
  doc.p do
    doc.text "Normal text "
    doc.b { doc.text "bold" }
    doc.text " and "
    doc.i { doc.text "italic" }
    doc.text " and "
    doc.u { doc.text "underlined" }
  end

  # Nested formatting (bold + italic)
  doc.p do
    doc.b do
      doc.i { doc.text "bold and italic" }
    end
  end
end

Lists

Bullet Lists

Ezdoc::Document.create("output.docx") do |doc|
  doc.ul do
    doc.li "First item"
    doc.li "Second item"
    doc.li { doc.b { doc.text "Bold item" } }
  end
end

Numbered Lists

Ezdoc::Document.create("output.docx") do |doc|
  doc.ol do
    doc.li "First"
    doc.li "Second"
    doc.li "Third"
  end
end

Tables

Ezdoc::Document.create("output.docx") do |doc|
  doc.table do
    doc.tr do
      doc.td "Header 1"
      doc.td "Header 2"
    end
    doc.tr do
      doc.td "Cell 1"
      doc.td { doc.b { doc.text "Bold cell" } }
    end
  end
end

Images

Images can be added to paragraphs, table cells, and list items. Supports PNG and JPEG formats.

Ezdoc::Document.create("output.docx") do |doc|
  # Simple image (uses native dimensions)
  doc.p do
    doc.image "photo.png"
  end

  # Image with explicit dimensions (inches, cm, or pixels)
  doc.p do
    doc.image "logo.png", width: "2in", height: "1in"
  end

  # Specify only width (height auto-calculated to maintain aspect ratio)
  doc.p do
    doc.image "banner.jpg", width: "5cm"
  end

  # Image with text in the same paragraph
  doc.p do
    doc.text "Company Logo: "
    doc.image "logo.png", width: "0.5in", height: "0.5in"
  end

  # Image in a table cell
  doc.table do
    doc.tr do
      doc.td "Product"
      doc.td do
        doc.image "product.jpg", width: "1in", height: "1in"
      end
    end
  end

  # Image in a list item
  doc.ul do
    doc.li do
      doc.image "icon.png", width: "16px", height: "16px"
      doc.text " List item with icon"
    end
  end
end

Complete Example

Ezdoc::Document.create("report.docx") do |doc|
  doc.p "Monthly Report"

  doc.p do
    doc.text "This report contains "
    doc.b { doc.text "important" }
    doc.text " information."
  end

  doc.p "Key Points:"

  doc.ul do
    doc.li "Revenue increased by 15%"
    doc.li "Customer satisfaction improved"
    doc.li { doc.i { doc.text "See appendix for details" } }
  end

  doc.p "Summary Table:"

  doc.table do
    doc.tr do
      doc.td "Metric"
      doc.td "Value"
    end
    doc.tr do
      doc.td "Revenue"
      doc.td "$1.2M"
    end
    doc.tr do
      doc.td "Growth"
      doc.td { doc.b { doc.text "15%" } }
    end
  end
end

API Reference

Method	Description
p(text)	Create a paragraph with text
p { }	Create a paragraph with block content
text(value)	Add text to the current context
b { }	Bold formatting
i { }	Italic formatting
u { }	Underline formatting
ul { }	Bullet list
ol { }	Numbered list
li(text)	List item with text
li { }	List item with block content
table { }	Table
tr { }	Table row
td(text)	Table cell with text
td { }	Table cell with block content
image(path, width:, height:)	Insert image (PNG/JPEG). Dimensions: "2in", "5cm", "100px", or integer pixels

Development

After checking out the repo, run bundle install to install dependencies. Then, run rake test to run the tests.

bundle install
bundle exec rake test      # Run tests
bundle exec rake rubocop   # Run linter
bundle exec rake           # Run both

License

The gem is available as open source under the terms of the MIT License.