# How paged.js works



If you have ever tried to lay out a website for printing or to publish a book in HTML, you’ll have experienced the limitations of styling meant for displaying scrolling text on screens. Paged.js helps make it possible to produce paginated material from your browser.



![](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/flux-page.png)



## W3C CSS modules

For printing pages you need very different rules from those used to  display content in the browser. For example, you’ll want to declare fixed sized pages rather than lay out a continuous flow of text. Books  also need many specific elements for the printed layout: margins, running headers, page numbers, a table of contents, and so on.

Fortunately the work on CSS at the W3C has resulted in special modules of the CSS standard for managing the layout of a HTML document during printing. These modules can be used in a print stylesheet with the media query `@media print{}`  and will only be applied when 
the web page is printed from the browser print dialog to create a PDF.

- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)  “describes the page model that partitions a flow into pages. (…) It  adds functionality for pagination, page margins, page size and  orientation, headers and footers, widows and orphans, and image  orientation.”
- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css-gcpm-3/)  defines many special requirements for the display of printed document  content: running headers and footers, footnotes, generated text for  cross-references or table of contents, PDF bookmarks, etc.
- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/) defines how and where CSS boxes can be fragmented, including across page breaks. (This module is not specific for print.)
- [ CSS page floats](https://www.w3.org/TR/css-page-floats-3/) defines how an element is to be removed from the normal flow and instead be placed into a different place depends on page. ([see the article “Page Media approaches: page floats”](https://www.pagedmedia.org/page-floats/))





## Support of W3C specifications in browsers



The previous CSS standard modules were written by the World Wide Web  Consortium (W3C). W3C publishes documents that define Web technologies  (including CSS) which are considered Web Standards. W3C modules are  published publicly throughout the process of their development until  they are finally released as a [W3C Recommendation](https://www.w3.org/2018/Process-20180201/#rec-publication). The modules we need for pagined media are at various stages of the process, but most are still in the [Working Draft](https://www.w3.org/2018/Process-20180201/#revised-wd) stage.

Browser developers can start implementing these recommendations at  any point, knowing they may change later, but the developers are not  obliged to implement all the CSS specifications until they become W3C  Recommendations.

Thankfully, browser developers have already taken some interest in  implementing parts of the Paged Media Working Draft standards and [@page rules have partial support](https://caniuse.com/#search=%40page) in Chrome, Firefox and IE. But it’s still difficult to use these browsers effectively for the output of paginated content.

So when it comes to producing paginated content from the browser,  this is where we are today: the rules for printing web pages from a  browser are written, and even standardised, but we can’t as yet use them  effectively.



## The paged.js library

The Paged.js library can be considered as a polyfill or previous CSS modules  - i.e., a code that implements a feature on web browsers that do not support the feature. But note that this is also our own interpretation of the implementation of this modules. 

We try to respect the specifications as much as possible, but they can be unclear and leave a certain degree of indeterminacy. In this case, we develop our own rules that seem to us to be the most technically appropriate and best meet the expectations of typographers and designers.

In your side, you just have to write the standardiezd CSS declarations and paged.js does its kind of magic. The library interprets the declarations and transforms them to other declarations that your browser understand by updating them with supported styles or replacing them with JavaScript implementations.



The library is build in differents javascript parts that work together: 

- the **chuncker** fragment the content into discrete pages, 
- the **polisher** transforms the CSS declarations,
- and the **previewer** call the preview of your book in the browser.



## The chunker

The chuncker part of paged.js getting your stylized content split into your page chunks. 

It 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  (page size minus margins size). It try to fit all into this container and looks for the overflowing content.

![The chunker put all your rendered content in a box and check the overflow](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/chuncker-1.png)

After, the script create a new box 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. Once you’ve got your content chunked, you’ll need to repeat the process anytime something changes. 



![The chuncker create a new box an put the overflow content in it](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/chuncker-2.png)

We will see that it is possible to control page breaks and change the size of the content area by changing the margins from one page to another according to a page master layout.



**Using CSS column**

Each content area is a CSS column independant from the other area. Using columns allows to have easier access to the linked properties already implemented in browsers like breaks elements properties or widows and orphans.
This doesn't prevent you from using the CSS column property in your content





## The polysher: polyfill the print declarations



With the polysher part, Paged.js also build new boxes to create layout pages and and place your content boxes on this pages. 

![](/Users/julieblanc/Documents/LOCAL_serveur/PagedMedia/pagedjs-documentation/images/div-pages.png)



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. We uses the CSS tree library to parse the CSS from text and replace `@page` rules with classes. The polisher also replaces calls like running headers or counter pages to CSS generated content functions with variable from the DOM.

Paged.js include support for a lot of things from the CSS (generated content for) paged media specifications, so that you can write CSS that conforms to that specifications. Paged.js do the work for apply it on the transformed DOM. 

Let's take the following CSS as an example:

```CSS
@page { 
  size: 148mm 210mm;
  margin-top: 10mm;
  margin-right: 20mm;
  margin-bottom: 25mm;
  margin-left: 15mm;
  
  @bottom-left {
    content: counter(page);
  }
  
  @bottom-center {
    content: string(title);
    text-transform: uppercase;
  }
  
}

h1#title {
  <!-- "Moby Dick" -->
  string-set: title content(text);
}
```



Paged.js transforms this into a CSS that is understandable to the browser:

```CSS
.pagedjs_page {	
	--pagedjs-string-title: "Moby Dick";
	margin-top: 10mm;
	margin-right: 20mm;
	margin-bottom: 25mm;
	margin-left: 15mm;
}

.pagedjs_page .pagedjs_margin-bottom-left::after {
	content: string(title); 
}

.pagedjs_page .pagedjs_margin-bottom-center::after {
	content: var(--pagedjs-string-title);  
	text-transform: uppercase;
}
```



This will apply to the transformed DOM (here simplified):

```html
<div id="page-1" class="pagedjs_page">
	<div class="pagedjs_pagebox">
    	<div class="pagedjs_margin pagedjs_margin-bottom-left hasContent">
				<div class="pagedjs_margin-content">
          <!-- ::after -->
        </div>
			</div>
      <div class="pagedjs_margin pagedjs_margin-bottom-center hasContent">
				<div class="pagedjs_margin-content">
          <!-- ::after -->
        </div>
			</div>
    </div>
		<div class="pagedjs_area">
			<!-- content of the page -->
		</div>
	</div>
</div>
```



Across this documentation, we will specify the CSS properties we implement and the one we use instead so that they can be interpreted by the browser.



## Previewer / Pagined rendering



The preview module of paged.js is specially dedicated to browsers. The previewer loads the modules, and uses the polisher and chunker to parse and layout the content. It build the preview of your document in the browser, so you can see exactly how things are going to look, and adjust your content accordingly.

With the script `paged.polyfill.js`, the previewer module is launched automatically and immediately (as soon as the page with the script is called). It will by default apply to all your HTML content. 

Using es6 modules you can add the previewer to your own scripts. You can also decide the delay to launch the paged.js script. We will see this in another part. Undertand that paged.js is just a script like others scripts. So, you can use it like you want.



## DOM modification



Paged.js modifies the DOM structure by adding some HTML elements to build and render your layout. This modification is only made during rendering, so there is no modification in your original HTML document.

It also adds references to every node (for example, classes to differentiate right or left pages). This gives us complete control over the page layout without any hacks. 

This documentation will provide more precisely for each CSS property the node references that are added to build and render the layout. You can access these elements in javascript directly with their classes if you want to go further with paged.js and add your own functions.