Notare

A Ruby gem for creating docx files with a simple DSL

Installation

Add this line to your application's Gemfile:

gem 'notare'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install notare

Usage

Basic Example

require 'notare'

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

Paragraphs

Notare::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.

Notare::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" }
    doc.text " and "
    doc.s { doc.text "strikethrough" }
  end

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

  # Show edits (strikethrough old, bold new)
  doc.p do
    doc.s { doc.text "old text" }
    doc.text " "
    doc.b { doc.text "new text" }
  end
end

Headings

Use h1 through h6 for document headings:

Notare::Document.create("output.docx") do |doc|
  doc.h1 "Document Title"
  doc.h2 "Chapter 1"
  doc.h3 "Section 1.1"
  doc.h4 "Subsection"
  doc.h5 "Minor heading"
  doc.h6 "Smallest heading"

  # Headings with formatted content
  doc.h2 do
    doc.text "Chapter with "
    doc.i { doc.text "emphasis" }
  end
end

Styles

Notare includes built-in styles and supports custom style definitions.

Built-in Styles

Notare::Document.create("output.docx") do |doc|
  doc.p "This is a title", style: :title
  doc.p "A subtitle", style: :subtitle
  doc.p "A quotation", style: :quote
  doc.p "puts 'code'", style: :code
end

Custom Styles

Define your own styles with text and paragraph properties:

Notare::Document.create("output.docx") do |doc|
  # Define custom styles
  doc.define_style :warning,
    bold: true,
    color: "FF0000",
    size: 14

  doc.define_style :note,
    italic: true,
    color: "0066CC",
    font: "Georgia"

  doc.define_style :centered,
    align: :center,
    size: 12

  # Apply to paragraphs
  doc.p "Warning message!", style: :warning
  doc.p "Centered text", style: :centered

  # Apply to text runs
  doc.p do
    doc.text "Normal text, "
    doc.text "important!", style: :warning
    doc.text ", and "
    doc.text "a note", style: :note
  end
end

Style Properties

Text properties:

• bold: true/false
• italic: true/false
• underline: true/false
• strike: true/false - strikethrough
• highlight: "yellow" - text highlight (see colors below)
• color: "FF0000" (hex RGB)
• size: 14 (points)
• font: "Arial" (font family)

Highlight colors: black, blue, cyan, darkBlue, darkCyan, darkGray, darkGreen, darkMagenta, darkRed, darkYellow, green, lightGray, magenta, red, white, yellow

Paragraph properties:

• align: :left / :center / :right / :justify
• indent: 720 (twips, 1 inch = 1440 twips)
• spacing_before: 240 (twips)
• spacing_after: 240 (twips)

Lists

Bullet Lists

Notare::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

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

Tables

Notare::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.

Notare::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

Line Breaks

Use br for soft line breaks within a paragraph (text continues in the same paragraph but on a new line):

Notare::Document.create("output.docx") do |doc|
  doc.p do
    doc.text "Line one"
    doc.br
    doc.text "Line two (same paragraph)"
    doc.br
    doc.text "Line three"
  end

  # Useful for addresses
  doc.p do
    doc.b { doc.text "Address:" }
    doc.br
    doc.text "123 Main Street"
    doc.br
    doc.text "Anytown, ST 12345"
  end
end

Page Breaks

Use page_break to force content to start on a new page:

Notare::Document.create("output.docx") do |doc|
  doc.h1 "Chapter 1"
  doc.p "Content of chapter 1..."

  doc.page_break

  doc.h1 "Chapter 2"
  doc.p "This starts on a new page."
end

Hyperlinks

Add clickable links with link:

Notare::Document.create("output.docx") do |doc|
  # Link with custom text
  doc.p do
    doc.text "Visit "
    doc.link "https://example.com", "our website"
    doc.text " for more info."
  end

  # Link showing the URL as text
  doc.p do
    doc.text "URL: "
    doc.link "https://example.com"
  end

  # Link with formatted content
  doc.p do
    doc.link "https://github.com" do
      doc.b { doc.text "GitHub" }
    end
  end

  # Links in lists
  doc.ul do
    doc.li do
      doc.link "https://ruby-lang.org", "Ruby"
    end
    doc.li do
      doc.link "https://rubyonrails.org", "Rails"
    end
  end

  # Email links
  doc.p do
    doc.text "Contact: "
    doc.link "mailto:hello@example.com", "hello@example.com"
  end
end

Complete Example

Notare::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, style:)	Create a paragraph with text and optional style
p(style:) { }	Create a paragraph with block content and optional style
text(value, style:)	Add text with optional style to the current context
h1(text) - h6(text)	Create headings (level 1-6)
b { }	Bold formatting
i { }	Italic formatting
u { }	Underline formatting
s { }	Strikethrough formatting
br	Line break (soft break within paragraph)
page_break	Page break (force new page)
link(url, text)	Hyperlink with custom text
link(url) { }	Hyperlink with block content
define_style(name, **props)	Define a custom style
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.