pdg XML → PDF

The pdg book · Chapter 01 of 10 · Start here

Hello, pdg

What pdg is, why it feels familiar if you know HTML and CSS, and your very first document — rendered live, right here on the page.

Welcome. I wrote pdg because I wanted to make PDFs the way I make web pages — by describing what is on the page and letting a layout engine work out where it goes. If you have ever written HTML and styled it with CSS, you already know most of what you need. This book takes you from a blank file to a finished, multi-page report, one runnable example at a time.

Every grey panel below is live. Edit the XML on the left and the page on the right re-renders as you type. Press Open in Playground to take any example full-screen. Nothing to install — let's write some XML.

Your first document

Here is a complete pdg document. It is the smallest thing that produces a PDF.

Try it — edit the source Open in Playground 
<document version="2.0">
  <config>
    <page size="A6" margin="20px" />
  </config>
  <pages>
    <page>
      <text size="24" bold="true">Hello, pdg.</text>
      <text size="13">My first page, set like type.</text>
    </page>
  </pages>
</document>

Try it: change Hello, pdg. to your name, or bump size="24" to 40. The page on the right follows along.

Three things are always present, and we will meet them properly in the next chapter:

  • <document> wraps everything — like <html>.
  • <config> sets up the page before any content — paper size, margins, fonts. Think of it as the <head>.
  • <pages> holds one or more <page> elements — the <body>, except a document can hold many pages, and pdg flows long content across them for you.

How pdg thinks (and how that maps to CSS)

A pdg document is a tree of elements, exactly like the DOM. Each element is handed a rectangle of space and answers one question: given this much room, how much of me fits? That single rule is what lets text wrap, columns balance, and content break cleanly onto the next page. You can read the full story in the architecture overview — but you do not need it to follow along.

Most of your CSS instincts transfer directly:

In CSS you reach for… In pdg you write…
<p>, <span>, text nodes <text> with inline <b>, <i>, <a>
display: flex; flex-direction: column <vertical>
display: flex; flex-direction: row <horizontal>
padding, margin, background, border style: attributes on any element
position: relative layers / z-index <stack>
<ul> / <ol> / <table> <list> / <table>
background <div>, border-radius <box>, <rect>

A few differences worth knowing up front, because they will save you confusion:

  • There is no cascade and no selectors. Style lives on the element, as an attribute. What you see is what you get — no specificity wars.
  • Sizes are explicit. There is no width: 50%. To split space you give children a flex weight (just like flex-grow), which we cover in Chapter 5.
  • Lengths are print units. px, pt, and mm — and 1px equals 1pt, so a number you would use in CSS lands in about the right place. More on this next chapter.

Running it yourself

In the browser you never have to leave this page. If you have the project checked out and want PDFs on disk, the command-line tool renders a document like so:

pdg build input.xml out.pdf

That is the whole toolchain: an .xml file in, a .pdf out. (Leave off the output name and it writes out.pdf; pdg validate input.xml parses and lays out without writing anything, just to surface warnings.)

Where this book goes

We will build up in the order you would actually learn it:

  1. The document skeleton — pages, sizes, margins.
  2. Text and typography — the thing PDFs are mostly made of.
  3. The box model — padding, borders, backgrounds, on any element.
  4. Layout with <vertical> and <horizontal> — the flexbox of pdg.
  5. Boxes, stacks, and spacing — cards and overlays.
  6. Lists and tables.
  7. Shapes and images.
  8. Multi-page documents — headers, footers, page numbers.
  9. A full page, built from scratch.

Whenever you want the exhaustive list of attributes for any element, the reference has a live example for every single one. This book is the guided tour; the reference is the map.

Turn the page when you're ready.