Paged.js

Make Books
with Browsers

Julie Blanc (@julieblancfr)
Julien Taquet (@john_tax)

HTML

circa 1991

CSS

circa 1996

Responsive

circa 2010

Printed book

circa 1452

Website

circa 1991

Single source publishing

Flux → Pagination

Missing features

Running headers, page number, facing pages, page float, etc.

A free and open source JavaScript library that paginates content in browser to create PDF outputs of any HTML content

Core team

Adam Hyde

Fred Chasen

Julien Taquet

Julie Blanc

Coko Foundation

Based on W3C web standards
Open and free tool (MIT licence)
Visual preview

Semantic content (HTML)

Regardons maintenent rapidement de comment marche paged.js. Je vais commencer par l'affichage dans un navigateur pour mieux vous expliquer. On commence avec un contenu balisé en HTML. Si on l'ouvre dans un navigateur, c'est un long flow.

CSS design

Vous pouvez designer ce contenu en CSS, assez classiquement

Paged.js script

Paginated display of content

Si vous ajouter le script de paged.js à votre page et un peu plus de CSS spécifique, vous pouvez à présent voir votre contenu affiché de manière paginé dans votre navigateur.

W3C / specifications

Respect of standards

Lorsque je parle de CSS spécifique, ce n'est pas notre invention, nous respectons les standards du World wide web consortium.

DevTools

Polyfill

Code that implements features on web browsers
that do not support the features

C'est à dire que Paged.js agit comme une sorte de polyfill pour certains modules CSS. Le script simule des fonctionnalités CSS qui ne sont pas encore disponibles sur les navigateurs

In parallel, the script reads your CSS file to have the information about the print style and transform your @page rules into classes that your browser understand today.
You write CSS that conforms to the standards, paged.js do the work for apply it on the transformed DOM.

How paged.js works ?

Now, let's have a deep look to how paged.js works

So, Paged.js take all your rendered document content - this means your content with all the design rules applied to it. It put this content in a box that have the size of your content area. It try to fit all into this container and looks for the overflowing content.

After, the script create a new bow and puts the overflow content in it. And look for the next overflowing content. Paged.js do it all over again until the book is done.

Paged.js also build new boxes to create pages and and place your content boxrs on this pages.

Here is an exemple of paged.js implementation.
On the left, it's the specifications defined by the W3C: the margins are divided into sixteen boxes where you can put generated content (like page number and running title).
On the right, it's an page rendered with paged.js. We use CSS and flexbox to create the margin boxes

This is what a document looks like when you inspect the DOM in the browser.
You can see the HTML elements created by paged.js.
This elements exists for the rendering only, nothing change in your initial HTML file.

Features

Now, let's see how the CSS works. I can't do this demo live because of time, so I took screenshots.

Page size and margins

First, you declare your page and margins in a @page rule. You can use inch or millimeters and even pixels for margins.

This is the result.
I added some basic CSS so you can see the spread.

Symetric margins

The left and right page have the same size but typically are symmetrical to each other and are centered on the gutter.
You can make a distinction between right and left pages with pseudo class selectors for @page rules and define different margins.

It's better.
Now, you can see here a chapter starting in the middle of the left page. We want it to start at the top of a right page. Let's add a page break.

Page breaks

You can write it like this to start the chapter on a right page..

And here the result. Note that if the chapter ends on a right page, paged.js will automatically a blank left page to start the new chapter on the good page.

Page breaks

You have different way to force the break of your content. You can break before or after a fragment. You can also specify if your want it to start on the next page or on the next left or right page.

Avoid page breaks

And if you want avoid a break, you have properties too.
In the first exemple, I want to avoid that a table is split in two pages.
In the second exemple, I want to avoid a break page after a title.

The CSS Generated Content for Paged Media Module introduce a new way to insert generated content into your document: you can define it into the margin boxes of your pages.

Page numbers

Here is an exemple with page numbers. I select the bottom left margin boxes of left pages and I call into it a specific counter named "page".
Also, you can style how the content appears in the margin boxes.

Now we have pages numbers. But we also want running headers.

String-set (running headers and footers)

You can use string and string-set properties to generate running headers and footers.
This code define that all my title level two will be running title with the string-set properties. After, I call this string in the bottom center margin boxes.

The string property act like a variable. It read your DOM and each time a new title level 2 is encountered, it change the variable from the page where that title appears.
This variable is passed into the margin boxes of the page and into all the following margin boxesuntil there is a new title.

This will add generated content to all left and right pages, included the pages created by page breaks. Problem, we have now generated contents into pages without content.

Pseudo class selectors for pages

Fortunately, the W3C has defined Pseudo class selectors for specific pages. We already see the left and right selector. But there is also a selector for the first page and a selector to specified a page number of your document. And there is also a selector for blank pages.

Blank pages

So you select your blank pages and remove the generated content like this.

This is the result.

Now, here could be pages in your book that may need a special layout: different background, different margins, different fonts.
You can use what is called “named pages” to define this.
Based on your HTML, you can bind a specific layout to any content.

Named pages

Imagine you want a specific layout for the pages of your frontmatter. That's how you will do with the code.
You define that all sections with the class frontmatter will have a page template named here "frontmatterLayout".
You create also a specific @page rule with the same name where you create new properties of the page.

You can mix pseudo selectors and named pages. Here, I define a layout for all my chapter and I select the first page of each chapter.
I move the counter page from bottom right to bottom left, I set a bigger font-size for the counter and I delete the running head.

Here, the result. You can see that the first page of the chapter has a different layout than the other pages below.

Columns layout

Paged.js also allow you to use all the properties already implemented in your browser. Here, I use columns to create a two-column layout.

You can also use hyphens, drop caps, shape-outside or svg as all of this is implemented in your browser.

Cross references

But let's go back to paged.js. You can also add generated content specific to your book content. Well know use case would be cross-references.
Here I want to indicate on which page is my figure three. But maybe this page number will change according to my layout. So I can't write it in my HTML, I have to generate it.

For that I can use the target-counter function. In my HTML, there is a link that refers to the unique identifier of my figure three.
In CSS, I generate the text of my cross-reference and target the page where the identifier is located.
You can use this function to create table of content and book indexes for example.

Open-source

Political point of view: free access
Pragmatic point of view: collaboration

Single source publishing

https://villachiragan.saintraymond.toulouse.fr

Paged.js Make Books with Browsers Julie Blanc (@julieblancfr) Julien Taquet (@john_tax)