Elements

Text style options: font, size, weight (:regular, :bold), style (:italic), color, letter_spacing, underline, strikethrough, link, opacity, kerning (default true), ligatures (default true), features (OpenType feature tags, e.g. %i[smcp onum]), hyphenate (true for English, or "de", "sv"; default off), align (:left, :center, :right, :justify), leading, orphans and widows (the fewest lines a page break may leave behind and carry over; default 1, a paragraph that cannot meet them moves whole). align: :justify stretches the spaces of wrapped lines to the full width; the last line, lines ending in a newline and lines without spaces stay left-aligned (tabs are never stretched). Colours are "#RRGGBB", "RRGGBB", "#RGB", [r, g, b] (0-255) or [c, m, y, k] (0-100).

text(content = nil, markup: false, keep_with_next:, break_inside:, anchor:, bookmark:, **style)

Plain strings are always literal. markup: true reads <b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href=""> and decodes numeric (', ') and all 252 HTML 4 named entities, each once: escape user data (ERB::Util.html_escape) before wrapping it in your own tags, and <b> stays the literal text <b>. A block builds styled runs in Ruby with plain, br, b, i, u, strikethrough, sub, sup, color, size, font and link.

text "Invoice INV-7", size: 22, weight: :bold
text "Net <b>30</b> days &mdash; <link href='mailto:[email protected]'>[email protected]</link>", markup: true
text { b "Total"; plain " due"; sup "1" }
text { |t| t.color "#4F46E5", @invoice.total }   # a block argument keeps your own self

text_style(**style) { … } sets the text defaults (font, size, colour, weight, align, leading, …) for everything built inside the block.

text_style(size: 8, color: "#6B7280") do
  text "Terms"
  text "Payment within 30 days."
end

box(padding:, background:, border:, radius:, width:, height:, overflow:, valign:, opacity:, at:, float:, margin:, link:, outset:, break_inside:, decoration:, rotate:, shadow:, align:, gap:, keep_with_next:, anchor:, bookmark:) { … }

box(background: "#F3F4F6", radius: 6, padding: [8, 12], border: { color: "#E5E7EB", width: 0.5 }) do
  text "AMOUNT DUE", size: 8, weight: :bold
  text "€ 7 330,00", size: 19, weight: :bold
end

A tilted, white-framed photo with a shadow — the pieces of a collage:

box(width: 180, padding: 4, background: "#FFFFFF", radius: 12, shadow: true, rotate: -3) do
  image "beach.jpg", width: 172, height: 129
end

• row(gap: 0, align: :top, break_inside: nil) { … }
• column(width: nil, align: nil, gap: 0, break_inside: nil, **box_options) { … }

width: is points, a fraction (0.5), :auto or nil (an equal share of what is left). A column takes every box option. align: on the row (:top, :middle, :bottom) places columns of different heights. Rows split across pages like a box, every column at the same break; a row holding a fixed-height column never splits.

row(gap: 24, align: :middle) do
  column(width: 0.5) { text "Invoice INV-7", size: 22, weight: :bold }
  column(width: :auto) { image "logo.png", height: 34 }
  column { text "Due 26 October", align: :right }
end

columns(count: 2, gap: 12, balance: true, rule: nil, align: nil) { … }

The block's content is one flow, poured through count columns newspaper style: column 1 top to bottom, then column 2. (A row is the other thing: columns side by side, each with content of its own.) Every column is (width - gap * (count - 1)) / count wide, and a column ends where a page would: between children, between the lines of a paragraph (honouring orphans: and widows:), inside boxes and tables by their own rules, never inside break_inside: :avoid. A heading with keep_with_next: true stays in the column of what follows it.

text "The sea wall is whole again", size: 30, weight: :bold
columns(count: 2, gap: 22, rule: { color: "#D1D5DB" }) do
  text "What it cost", weight: :bold, keep_with_next: true
  text body, align: :justify, orphans: 2, widows: 2
  image "bay.png", width: 1.0
end
text "A note across the page, below the tallest column."

• balance: true ends the columns at nearly the same height wherever the content ends: on the last page of the block and before a page_break inside it. The height is the shortest at which everything fits, and the columns are filled evenly in it: the first takes what fits, and what it leaves is balanced through the columns after it in the same way. Ten lines in three columns are 4, 3 and 3, what cannot be shared going to the earlier columns. The break rules hold, so a heading, a box or orphans: and widows: can keep the columns further apart than a line, and a column that ends above a block that cannot split may stay shorter than the one after it. balance: false fills each column to the height available before the next starts.
• Across pages. A block that does not fit fills the height left on the page, every column full, and continues on the next page; the last page is balanced. Below other content it starts only when every column takes something in the height left, and otherwise moves to the next page. A page_break inside ends the page. What follows the block starts below its tallest column.
• rule: true or { color:, width: } draws a line in the middle of each gap, an artifact in a tagged PDF.
• count: 1 lays out like a group. count: must be an Integer of at least 1 and gap: a number of at least 0, or ArgumentError is raised.
• Nesting. columns works inside a box, a column and another columns.
• Tagged PDF. Reading order is column 1, then column 2; a paragraph split across columns is one P, as it is across pages. Links, anchors, bookmarks and table_of_contents page numbers work inside.
• A child too tall for a column at the top of a page is kept and reported as an overflow warning.

examples/newsletter.rb is a complete page. In html, column-count, columns: <n> and column-gap map to it.

group(gap: 0, align: nil, keep_together: false, keep_with_next: nil, anchor: nil, bookmark: nil) { … }

A vertical group of children. keep_together: true moves the whole group to the next page rather than splitting it.

group(keep_together: true) do
  rule height: 1, color: "#E5E7EB"
  text "Thank you for your business", weight: :bold
end

wrap(gap: 0, row_gap: gap, align: :left) { … } — children side by side at their own widths, wrapping onto new rows. It splits between rows.

wrap(gap: 6, row_gap: 4) do
  %w[ruby pdf layout].each { |tag| box(width: :auto, padding: [2, 8], radius: 8, background: "#EEF2FF") { text tag } }
end

table(rows, widths: nil, width: :auto, header: false, split_rows: false, cell: {}, anchor:, bookmark:) { |t| … }

• rows is an Array or any Enumerable of rows. An Enumerator (lazy or not) whose table has a width for every column is read as pages reach it (below).
• Cells are strings, layout nodes, procs built with the DSL (-> { image logo }) or components.
• widths: per column: points, a fraction of the table (0.25), or nil for a share of the rest. width: :auto, :full or points.
• header: true (one row) or a row count; header rows repeat after every page break.
• cell: defaults for every cell: padding (5), borders (all four), border_width (0.5), border_color, plus background, color, weight, style, size, font, align, valign, letter_spacing, leading and markup.

Selections and zebra stripes

t.row(0), t.rows(-1), t.column(1), t.columns(1..) and t.cells select cells (chainable: t.row(-1).columns(3..)); assign one option (t.columns(1..).align = :right) or several with set. t.zebra(color:, from: 0, to: nil, every: 2) stripes rows.

table(rows, width: :full, widths: [nil, 45, 80, 85], header: true, cell: { padding: [7, 8], borders: [] }) do |t|
  t.row(0).set(background: "#4F46E5", color: "#FFFFFF", weight: :bold)
  t.columns(1..).align = :right
  t.zebra(from: 1, color: "#F9FAFB")
  t.row(-1).set(weight: :bold, borders: [:top])
end

Spans

A cell may be { content:, colspan:, rowspan: } plus any cell option. Rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections.

table([
  [{ content: "Q1", rowspan: 2 }, "January", "12"],
  ["February", "15"],
  [{ content: "Total", colspan: 2, align: :right, weight: :bold }, "27"]
])

DSL cells

table([
  ["Logo", -> { image "logo.png", height: 16 }],
  ["Status", StatusPill.new("PAID")]
])

Rows taller than the page

A row taller than the page continues on the next page, cut through its cells, with the header repeated. split_rows: true cuts any row that reaches the page bottom instead of moving it whole — useful for long tables of tall rows.

Rows read as pages reach them

Rows given as an Enumerator, lazy or not, to a table with a width for every column (points or fractions) are read as pages reach them: the table holds the rows of the page being filled and the one after them, and none before its first page. With incremental a price list of a million rows peaks at 130 MB, where the same rows as an Array peak at 2.8 GB (see Large documents).

orders = Order.preload(:customer).find_each.lazy.map { |o| [o.number, o.customer.name, o.total] }
rows = [%w[Order Customer Total]].each + orders
table(rows, header: true, widths: [80, 0.5, 90]) do |t|
  t.row(0).weight = :bold
  t.columns(2).align = :right
  t.zebra(from: 1, color: "#F4F4F4")
end

The header rows, zebra, split_rows, cells spanning columns and selections by index from the start (t.row(0), t.rows(1..), t.columns(…)) work as for an Array, applied to each row as it is read; a proc or component cell is built then, in the text style the table was given in. What needs the end of the table raises an ArgumentError: a row counted from the end (t.row(-1), t.rows(1..-2)), a cell spanning rows, and a row with more columns than widths. An Enumerator with a column without a width is read whole when the table is built, as an Array is.

image(path_or_io, width: nil, height: nil, fit: nil, align: nil, opacity: nil, float: nil, margin: nil)

Aspect ratio is preserved when only one of width/height is given; fit: [w, h] scales the image to fit inside that box; with neither, one pixel is one point. An image is never wider than the space it is given. float: :left or :right takes it to that side, and the text that follows wraps beside it (Floats). Details on Images and SVG.

image "logo.png", height: 34, align: :right
image StringIO.new(blob.download), fit: [120, 80]
image "bay.jpg", float: :left, width: 0.4, margin: 12, alt: "The bay at dawn"

float: :left or :right on an image or a box takes it to that edge of the flow it is written in: the page body, a box, a column or a table cell. What follows it in that flow starts at its top and wraps beside it, and takes the full width again below it, in the middle of a paragraph if need be. examples/article.rb is a page built this way.

image "bay.jpg", float: :left, width: 0.4, margin: 12, alt: "The bay at dawn"
text story, align: :justify                     # beside the photo, then below it

box(float: :right, width: 170, margin: { left: 16, bottom: 6 }, padding: 10, role: :blockquote) do
  text "The view is everywhere.", size: 13, style: :italic
end
text more                                       # around the pull quote

Anything but :left and :right raises ArgumentError, as do margin: without float: and float: together with at:. Text wraps along the float's rectangle, never along a shape.

svg(source_or_path, width: nil, height: nil, color: "#000000", align: nil) — markup String or a path to a .svg file. currentColor takes color:.

svg "icons/check.svg", width: 14, color: "#0F766E"

barcode(data, type: :code128, level: nil, module_size: nil, width: nil, height: nil, color: "#000000", quiet_zone: true, native: nil, align: nil, alt: nil) encodes data in Ruby and draws it as one filled path: sharp at any zoom and on any printer.

barcode "SX0042771903", module_size: 1.5, height: 44          # Code 128
barcode "400638133393", type: :ean13, height: 40              # the check digit is added
barcode "https://track.example/SX0042771903", type: :qr, level: :q, width: 60
barcode "SX0042771903", type: :datamatrix, module_size: 2

module_size: is the width of the narrowest bar (a square one's module) in points, 1 by default (2 for a square one), or width: sets it from the whole width, quiet zones included. A barcode never takes more than the width it is given: its module is made smaller to fit. In a monochrome render it is put on the printer's dot grid, a whole number of dots a module. The digits under an EAN-13 are not drawn; write them with text. native: true asks to_zpl to have a label printer draw it with its own command, see Label printers.

All of them were decoded with ZBar from pictures of what they draw: Code 128 and EAN-13 samples, and QR codes filled to capacity at versions 1 to 40 and every level. Every Data Matrix size, filled to capacity, was read by dmtxread (libdmtx) and is module for module the symbol libdmtx writes for the same data in ASCII encodation.

stack(gap: 0, align: nil) { … } is a container whose ordinary children form the base and set the height. layer(top:, right:, bottom:, left:, width:, height:, **box_options) { … } inside it is a box painted over the base, placed by insets from the stack's edges and taking no space. Insets, width: and height: are points, or a fraction of the stack's width (horizontal) or height (vertical) when given as a Float between -1 and 1 or a Rational (1/3r); negative insets overhang. A layer takes every box option, so rotate:, shadow:, padding:, background: and radius: make tilted, framed snapshots. A stack never splits: it moves to the next page whole.

Overhanging layers paint past the stack, so wrap it in a box(padding:) at least as big as the overhang to keep them inside the page margins (what examples/postcard.rb does):

box(padding: 18) do
  stack do
    box(width: :auto, radius: 16, shadow: true) do
      image "sea.png", width: 228, height: 171, fit: :cover, radius: 16, alt: "The bay at dawn"
    end
    layer(bottom: -18, left: -18, width: 0.4, rotate: -3, padding: 4, background: "#FFFFFF", radius: 12, shadow: true) do
      image "hills.png", width: 83, height: 62, fit: :cover, radius: 8, alt: "Hills above the village"
    end
    layer(top: -18, right: -18, width: 1/3r, rotate: 2, padding: 4, background: "#FFFFFF", radius: 12, shadow: true) do
      image "stone.png", width: 68, height: 68, fit: :cover, radius: 8, alt: "A sandstone wall"
    end
  end
end

Without left:/top: a layer sits at the stack's top-left; without width: it takes its content's natural width (at most the stack's). In a tagged PDF the base and the layers attach in paint order.

canvas(height:, at: nil, width: nil) { |canvas, rect| … } reserves height points and hands the block the canvas — clipped to the reserved rectangle — and that rectangle (rect.x, rect.y, rect.width, rect.height, top-left page coordinates).

Canvas methods: fill_rect(x, y, w, h, color:), rounded_rect(x, y, w, h, radius:, fill:, stroke:, line_width:, dash:) (per-corner radii), circle(cx, cy, r, fill:, stroke:), line(x1, y1, x2, y2, color:, width:, dash:, cap:), path(fill:, stroke:, …) { |p| p.move_to; p.line_to; p.curve_to; p.close }, clip(x, y, w, h, radius:) { … }, image(image, x:, y:, width:, height:) and link(x, y, w, h, target).

canvas(height: 40) do |canvas, rect|
  bars.each_with_index do |width, index|
    x = rect.x + bars.first(index).sum
    canvas.fill_rect(x, rect.y, width, rect.height, color: "#111827") if index.even?
  end
end

rotate(degrees, around: [x, y]) { … } paints the block turned clockwise around a page point, as CSS rotate() does; transform([a, b, c, d, e, f]) { … } applies any affine matrix given in the same top-left space. Shapes, images and text inside follow the transform. Link and form widget rectangles are annotations in untransformed page space, so a link inside a rotated block keeps its unrotated rectangle.

canvas(height: 120) do |canvas, rect|
  canvas.rotate(-3, around: [rect.x + 60, rect.y + 60]) do
    canvas.image(photo, x: rect.x, y: rect.y, width: 120, height: 120)
  end
end

• rule(height: 1, color: "#000000", width: nil, radius: 0) — a filled horizontal bar.
• spacer(height) — vertical space, dropped when it lands on a page break.
• page_break — forces what follows onto a new page.

rule height: 3, color: "#4F46E5"
spacer 18
page_break

• ul(style: nil, gap: 4, indent: nil, marker_gap: 6, marker_color: nil) { … } — style: is :disc, :circle, :square, :dash or any String; unstyled nested lists cycle disc → circle → square.
• ol(format: :decimal, start: 1, suffix: ".", gap: 4, indent: nil, marker_gap: 6, marker_color: nil) { … } — format: is :decimal, :alpha, :upper_alpha, :roman, :upper_roman or a Proc (n) -> String. Markers right-align so bodies line up.
• li(string, **text_style) or li(gap: 0) { … } — a paragraph, or a block of any elements, including nested lists.

Any node added inside a list (not only li) becomes an item. Items split across pages; the marker stays with the first line.

ol(format: :upper_roman, marker_color: "#0F766E") do
  li "Introduction"
  li do
    text "Highlights"
    ul(style: :dash) { li "Revenue up 18%"; li "Two new markets" }
  end
end

• anchor(name) — a named link target (link: "#name"); it moves to the next page with what follows it. anchor: is also an option on text, box, group and table.
• bookmark(title, level: 1, open: false) — a standalone outline entry; bookmark: (a title or { title:, level:, open: }) is also an option on text, box, group and table.
• table_of_contents(levels: 1.., leader: :dots, indent: 12, number_width: nil, gap: 4, **text_style) — one linked row per bookmark with its page number.

text "Contents", size: 18
table_of_contents(levels: 1..2, leader: :line)
text "Introduction", size: 16, bookmark: "Introduction", anchor: "intro"

The full story is on Links, bookmarks and contents.

text_field, checkbox, radio, select and signature_field make a PDF fillable: each takes a name and lays out like a box, or sits at at: [x, y]. Their options, naming, fonts and accessibility have a page of their own: Forms.

html and markdown render user content with the elements above; their parsers load on first use.

def view_template
  html @post.body.to_s,                                   # ActionText
       images: ->(src) { blob_path_for(src) },            # path, IO or nil (skipped with a warning)
       styles: { h1: { size: 22 }, a: { color: "#0F766E" }, code: { font: "JetBrains Mono" } }
  markdown File.read("NOTES.md"), base_path: "docs", bookmarks: true
end

• Images come from images: (called with the src) or from files under base_path:; sources that resolve nowhere, point outside base_path or are remote URLs are skipped with a SkippedImage warning. Nothing is ever fetched over the network.
• styles: is deep-merged into the defaults: h1–h6 (scale: of the text size, or size: in points; bold, keep_with_next), p, a (colour, underline), code (font:; register a monospace family for inline and block code, otherwise the text font is used), pre and blockquote (box options), hr (rule options), table (cell: options, header: text style), ul and ol (list options: gap:, indent:, marker_gap:, marker_color:, plus style: for ul and format:/suffix: for ol), li (text style) and img (max_width:, and float_margin: for a floated image without a CSS margin).
• Links are written only for http, https, mailto and tel hrefs (and #anchor); anything else (javascript:, data:, a relative path) keeps its text without a link and is reported as a DroppedLink warning. links: %w[http https] changes the list, links: :all keeps every href from a trusted source.
• gap: spaces the blocks (default 6); bookmarks: true adds h1–h3 to the PDF outline.
• html reads a subset of CSS from <style> elements and inline style attributes (see What CSS is read); what it does not read is reported once as an UnsupportedCss warning. markdown reads none.
• max_depth: (default 64) is how deep the source may nest: HTML elements inside one another, or Markdown block quotes and lists. What lies deeper is flattened into the deepest element kept, so its text stays and its structure goes, and a NestingLimit warning says how deep the source went. Block quotes and lists also stop indenting after twelve levels, where they would leave their text no width; that is reported the same way.

What CSS is read

html applies <style> rules and inline style attributes on top of styles:. The cascade is the usual one: the element's defaults from styles:, then stylesheet rules by specificity (id over class over element, the later rule winning a tie), then the inline style, then the element's own mark (<b>, <i>, <u>, <s>).

Selectors are an element name, .class, #id, any compound of them (p.lead, td.n.total), comma lists and *. Selectors with combinators or pseudo-classes (ul li, a > b, a:hover) are ignored and reported. At-rules are skipped, except that rules inside @media print and @media all are read.

margin and its sides are read in the order of the cascade: a side wins over a margin declared before it or by a lesser rule, and a margin takes back the sides declared before it. <font color size>, <center> and <img align="left|right"> (a float) are read the same way. Everything else (display, float on anything but an image, position, font-family, line-height, em lengths outside font-size, auto margins, a negative margin-left or margin-right, url() values, inline backgrounds) is ignored and named in the UnsupportedCss warning, so strict catches content that expects more than this. No value is ever fetched: url() and @import are dropped.

html <<~HTML
  <style>
    .note { background-color: #FEF3C7; padding: 8pt; margin: 6pt 0; break-inside: avoid }
    td.amount { text-align: right; width: 25% }
    h2 { page-break-before: always; color: #0F766E }
  </style>
  <div class="note"><p><b>Note.</b> Prices include VAT.</p></div>
HTML

html and markdown are meant for content you did not write (a CMS body, a comment, an ActionText field). Nothing in that content can reach outside the document, and parsing it is bounded: nesting is capped and time grows with the input's length. How much input you accept, and so how many pages it renders to, is yours to bound:

• No requests. Remote images are never fetched; an image is read only from images: or from under base_path:, and a path that climbs out of it is skipped (SkippedImage).
• No surprising links. Only http, https, mailto and tel hrefs (and #anchor) become links (DroppedLink for the rest), so a javascript: or file: href is plain text.
• No scripts, no fetched styles. script, template and title content is dropped and raw HTML inside Markdown stays literal text. CSS is read only for the fixed list of properties above: url() and @import are dropped unread, and nothing in a style can position content outside the flow or hide it.
• Bounded nesting. Five thousand nested <div>s, block quotes or lists render flattened, with a NestingLimit warning, instead of exhausting the stack (the svg element guards its own nesting the same way, at 128 levels). Emphasis nests without recursion, at most 64 brackets wait for their ], and a link label is at most 999 characters, so parsing takes time in proportion to the input.
• Size is yours to bound. There is no limit on how much text is rendered: a megabyte of input is a few hundred pages. Cap the length of what you accept before you render it, and use strict (or read document.warnings) when a warning should stop the document.