Commit 98ba1c8d authored by Julie Blanc's avatar Julie Blanc

Merge branch 'master' into 'master'

Copyedits and add consistency of markdown formatting using Prettier

See merge request !1
parents f5b6d1ee be37bb6a
# FAQ
**CSS Variables doesn't work in @page directive (page size and margin size)**
**CSS Variables don't work in @page directive (page size and margin size)**
Unfortunately Chromium/Chrome doesn’t understand css-properties when printing. We're looking at options to transform those into fixed values for printing, until Chromium/Chrome supports it. In the meantime, do not use the variables in these declarations by giving fixed values (calculated in advance).
......@@ -12,15 +10,15 @@ Unfortunately Chromium/Chrome doesn’t understand css-properties when printing.
Paged.js fragments all the content of your document, which means it will take the `<body>` tag from your document and transform your content into pages.
* If an image don't have the place to fit in a page, it's push in the next page.
- If an image don't have the space to fit in a page, it is pushed into the next page.
---
**Mixing page size or page orientation**
Blink (Chromium/Chrome rendering engine) doesn’t support mixed orientation or mixed size when it comes to print, so you can only set one orientation and one size per file (generated PDF).
Blink (Chromium/Chrome's rendering engine) doesn’t support mixed orientation or mixed size when it comes to print, so you can only set one orientation and one size per file (generated PDF).
The way that paged.js support landscape and portrait let you preview on screen, but when it comes to print, you would need to print two different files and merge those. We're looking at options for postprocessing PDF (using Ghostscript) to handle this kind of tasks automatically, but it's not there yet.
The way that paged.js supports landscape and portrait lets you preview on screen, but when it comes to print, you would need to print two different files and merge them. We're looking at options for postprocessing PDF (using Ghostscript) to handle this kind of tasks automatically, but it's not there yet.
---
......@@ -28,12 +26,12 @@ The way that paged.js support landscape and portrait let you preview on screen,
If paged.js makes an infinite loop when rendering (generating empty pages or pages with the same content), it's probably because it can't fit an inline element into the page size you defined
Paged.js checks the overflow only horizontally in the page. If you have elements that are larger than the page vertically, you may have rendering problems because paged.js can't get the element into the page. (For the vertical writing direction, it will be the opposite)
Paged.js checks the overflow only horizontally in the page. If you have elements that are larger than the page vertically, you may have rendering problems because paged.js can't get the element into the page. (For the vertical writing direction, it will be the opposite)
This often happens with `<pre>` or `<table>` (`<tr>`, `<th>`) elements. You need to add line breaks, which are possible with css (https://developer.mozilla.org/en-US/docs/Web/CSS/white-space)
This often happens with `<pre>` or `<table>` (`<tr>`, `<th>`) elements. You need to add line breaks, which is possible with css (https://developer.mozilla.org/en-US/docs/Web/CSS/white-space)
---
**Styling div and section elements**
Paged.js modifies the DOM structure by adding some HTML elements to build and render your layout. It adds a lot of `div ` elements. When you make your style sheet, we don't recommend that you call `div` and `section` tag names to apply your styles. You may get an unexpected rendering because your styles will apply to unwanted elements. Instead, use custom class to select the items you want.
\ No newline at end of file
Paged.js modifies the DOM structure by adding some HTML elements to build and render your layout. It adds a lot of `div` elements. When you make your style sheet, we don't recommend that you call `div` and `section` tag names to apply your styles. You may get an unexpected rendering because your styles will apply to unwanted elements. Instead, use custom class to select the items you want.
# Getting Started with Paged.js
## A quick introduction of paged.js
Paged.js is a free and open-source library to paginate content in the browser to create PDF output from any HTML content based on the W3C specifications.
## A quick presentation of paged.js
Paged.js is a free and open-source library to paginate content in the browser to create PDF outputs from any HTML content based on the W3C specifications.
With Paged.js you can do automated typesetting adaptable to any workflows. It will fragment your content, read and apply your print declarations and present a paginated rendering of the HTML document.
With Paged.js you can do automated typesetting that is adaptable to any workflow. The library will fragment your content, read and apply your print declarations and present a paginated rendering of the HTML document.
### Visual preview and command line version
With paginated content in the browser, Paged.js makes it possible to have a visual preview of the printed rendering directly in web browsers with a graphical interface. This allows designers to access development tools to make changes on the fly and control the rendering of the composition (easy debugging). It's also possible to insert Paged.js into other tools and to propose to users to configure their graphical rendering by adding functionalities.
Paged.js can easily be inserted into automated workflows thanks to the command line interface version (using an headless browser) that can generate a PDF from scriptable and automated commands.
Paged.js can easily be inserted into automated workflows thanks to the command line interface version (using an headless browser) that can generate a PDF from scriptable and automated commands.
### W3C specifications
Paged.js is based on the CSS standards written by the World Wide Web Consortium (W3C). It acts like a sort of polyfill(*) to supports some CSS print modules in recent browser: it can parse CSS stylesheets, polyfill the print declarations (by updating them with supported styles or replacing them with JavaScript implementations) and present a paginated rendering of the HTML document using the fragmentation provided by CSS columns.
(*) A [polyfill](https://en.wikipedia.org/wiki/Polyfill_(programming)) is code that implements a feature on web browsers that do not support the feature.
W3C CSS modules implemented by paged.js :
- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)
- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css-gcpm-3/)
- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/)
Paged.js is based on the CSS standards written by the World Wide Web Consortium (W3C). It acts like a sort of polyfill(\*) to supports some CSS print modules in recent browser: it can parse CSS stylesheets, polyfill the print declarations (by updating them with supported styles or replacing them with JavaScript implementations) and present a paginated rendering of the HTML document using the fragmentation provided by CSS columns.
(\*) A [polyfill](<https://en.wikipedia.org/wiki/Polyfill_(programming)>) is code that implements a feature on web browsers that do not support the feature.
W3C CSS modules implemented by paged.js :
- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)
- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css-gcpm-3/)
- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/)
### A community
......@@ -44,21 +30,16 @@ The code of paged.js is open-source with a MIT license and the development is co
You can find the source code of paged.js on the repo of our self-healing gitlab: https://gitlab.pagedmedia.org/tools/pagedjs
We have several tools to help designers and discuss the addition of new features. You can add issues to the repo to suggest new features or simply report problems. But the easiest way to talk to us (if you're not using gitlab) it's to join us on our self-hosted chat: https://mattermost.pagedmedia.org/
We have several tools to help designers and to discuss the addition of new features. You can add issues to the repo to suggest new features or simply report problems. But the easiest way to talk to us (if you're not using gitlab) is to join us on our self-hosted chat: https://mattermost.pagedmedia.org/
## Running paged.js
How to start with paged.js? The first thing is to make the script work on your document. For that, you need a few things:
How to start with paged.js? The first thing is to make the script work on your document. For that, you need a few things:
* your usual html and css files,
* the paged.js script,
* a (local) server,
* a web browser.
- your usual html and css files,
- the paged.js script,
- a (local) server,
- a web browser.
https://www.startpage.com/fr/
......@@ -72,21 +53,19 @@ You can use the hosted version of the script, just copy this in the `head` of yo
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
```
If you want to specify the release number of the script you are using, the different releases of the script will be available here: https://gitlab.pagedmedia.org/tools/pagedjs/releases. By default, the link bellow go to the latest release.
If you want to specify a specific version of paged.js, the different releases of the script will be available here: https://gitlab.pagedmedia.org/tools/pagedjs/releases. By default, the link below goes to the latest release.
To use the script locally, without an internet connection, just copy the script into a file and change the link to your script, something like:
To use the script locally, without an internet connection, just copy the script into a file and change the link to your script to something like:
```HTML
<script src="js/paged.polyfill.js"></script>
```
The script will start automatically when you go to your document from the browser. It will apply to all your content and fragment it into different pages. If you need to run other scripts before paged.js starts, if you want to integrate it into a tool or simply if you want delay its launch, we will see that in another part.
The script will start automatically when you go to your document from the browser. It will apply to all your content and fragment it into different pages. It is possible to run other scripts before paged.js starts, to integrate it into a tool or simply to delay its launch: we will see that later in this guide.
**Option 2: Developpement version**
To get setup with the developement version, clone the repository and run the project using npm (you need to have git and npm installed):
To get set up with the developement version, clone the repository and run the project using npm (you need to have git and npm installed):
```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs.git
......@@ -98,90 +77,70 @@ $ npm start
Link the script with your document:
<script src="http://localhost:9090/dist/paged.polyfill.js"></script>
All you need to know about setup, development and testing with the local dev-server is available in the README.md of the repo.
All you need to know about setup, development and testing with the local dev-server is available in the README.md of the repo.
### Use a local server
Paged.js need to access your files via a local server to read the css properties you write. There is a lot of way to create and lunch a local server. If you're not familiar to Linux, the easiest way is to use ready-to-use local web development solution like [WAMP](http://www.wampserver.com/) (for window) or [WAMP](https://www.mamp.info/en/) (for Mac).
Paged.js need to access your files via a local server to read the CSS properties you write. There is a lot of way to create and lunch a local server. If you're not familiar with Linux, the easiest way is to use ready-to-use local web development solution like [WAMP](http://www.wampserver.com/) (for Windows) or [WAMP](https://www.mamp.info/en/) (for Mac).
You can find all the documentation on their respective websites, globally:
1. download the package and follow the step of your usual system installation manager.
2. add the folder of your project in the folder automatically create by the application, typically in `c:\wamp\www` for WAMP or in `/Applications/MAMP/htdocs/`
3. Start the local server
4. In your favorite browser, go to the local address provided by your application (like`http://localhost:8888` for example)
Note: With some browsers and some OS, you may not need a local server for paged.js to work. To find out, simply open your HTML page (linked to the polyfill). If the paginated content appears, you don't need a local server.
You can find all the documentation on their respective websites. Broadly, what you need to do is:
1. Download the package and follow the step of your usual system installation manager.
2. Add the folder of your project in the folder automatically created by the application, typically in `c:\wamp\www` for WAMP or in `/Applications/MAMP/htdocs/`.
3. Start the local server.
4. In your favorite browser, go to the local address provided by your application (like `http://localhost:8888`).
Note: With some browsers and some operating systems, you may not need a local server for paged.js to work. To find out, simply open your HTML page (linked to the polyfill). If the paginated content appears, you don't need a local server.
### Which browser to use?
We really want paged.js to work with all the browsers around, but we can't manage right now. There are several reasons for this which are explained below. To be quick: **Paged.js only works in Chromium and derivative (Chrome, Brave, etc.) and in recent versions, after mid-2017**.
We really want paged.js to work with all the browsers around, but we can't manage right now. There are several reasons for this which are explained below. To be quick: **Paged.js only works in Chromium and derivative (Chrome, Brave, etc.) and in recent versions, after mid-2017**.
#### Support of @page { size }
#### Support of @page { size }
Paged.js act like a sort of polyfill but there is one thing we can't manage and we need to print: it's the support by the browser of the `@page { size }` property. This property will allow you to create the PDF at the right size when it is generated. It's only supported in some browsers (see the list below):
Paged.js acts like a sort of polyfill but there is one thing we can't manage that we need to print correctly: the support by the browser of the `@page { size }` property. This property will allow you to create a PDF at the right size when it is generated. It's only supported in some browsers:
- Chromium
- Google Chrome
- Brave
- Opera
We know that many of you are attached to Mozzila Firefox (and so are we), it is still possible to use it but you will have to manually change the PDF size when you generate it (in the custom sizes). De careful to calculate bleeds and crop marks if you add it.
We know that many of you are attached to Mozilla Firefox (and so are we). It is still possible to use it but you will have to manually change the PDF size when you generate it (in the custom sizes). Be careful to calculate bleeds and crop marks if you add it.
#### Support of CSS grid
You must also use a recent version of these browsers because we use some CSS grid module properties for the construction of the pages. CSS grid is supported in most browsers since mid-2017. You can see here if your browser supports CSS grid: https://caniuse.com/#feat=css-grid
You must also use a recent version of these browsers because we use some CSS grid module properties for the construction of the pages. CSS grid is supported in most browsers since mid-2017. You can see here if your browser supports CSS grid: https://caniuse.com/#feat=css-grid
#### Different rendering between browsers
The result will not always be the same from one browser to another because they don't use the same browser engine. For example, line-height is not managed in the same way on Firefox and Chrome. The result will also not be the same depending on the OS you are using. For example, hyphenation is managed in Chrome only on Apple OSX.
We recommend staying on the same browser and OS for the design and generation of the PDF to avoid unpleasant surprises.
The result will not always be the same from one browser to another because they don't use the same browser engine. For example, line-height is not managed in the same way on Firefox and Chrome. The result will also not be the same depending on the OS you are using. For example, hyphenation is managed in Chrome only on Apple OSX.
We recommend staying on the same browser and OS for the design and generation of the PDF to avoid unpleasant surprises.
## Generating a PDF
Paged.js transforms your content so that it can be viewed in a browser. PDF generation can be done in two ways:
Paged.js is a viewer for your content paged in the browser. The PDF generation can be done by two way:
* using the print features of your browser,
* using the [pagedjs-cli](https://gitlab.pagedmedia.org/tools/pagedjs-cli) tool based on paged.js and [Puppeteer](https://github.com/GoogleChrome/puppeteer).
- using the print features of your browser,
- using the [pagedjs-cli](https://gitlab.pagedmedia.org/tools/pagedjs-cli) tool based on paged.js and [Puppeteer](https://github.com/GoogleChrome/puppeteer).
### Option 1: with a browser
1. Simply click on the “Print” button of your browser.
1. Click on the “Print” button of your browser.
2. Change the *Destination* to "Save as a PDF file”.
2. Change the _Destination_ to "Save as a PDF file”.
3. In the avanced settings:
* Set *Margins* to “none”,
* Remove the option “Headers and footers”,
* Select the option “Background graphics”.
The way paged.js work, it doesn't use the print engine from the browser to define the margins, the breaks or the headers and footers. This is why you need to remove this option. Printing without the library give a different output.
- Set _Margins_ to “none”,
- Remove the option “Headers and footers”,
- Select the option “Background graphics”.
Paged.js doesn't use the print engine from the browser to define the margins, page breaks or headers and footers, which is why you need to change these option. Printing without the library give a different output.
### Option 2: with pagedjs-cli
The command line version of paged.js uses a headless browser to generate a PDF (chromium). So you can use paged.js in fully automated workflows. With the command line version, you don't need to call the paged.js script in your document, it will be done automatically.
The command line version of paged.js uses a headless browser (that is, one without a graphical interface) to generate a PDF. The browser used is Chromium. This means that you can use paged.js in fully automated workflows. With the command line version, you don't need to call the paged.js script in your document: it will be done automatically.
First, download and install pagedjs-cli with your terminal (you need to have git and npm installed):
......@@ -191,13 +150,13 @@ $ cd pagedjs-cli
$ npm install -g pagedjs-cli
```
Then, in a new window terminal, go to the folder where the code of your document is located (use the `cd` command) and generate your PDF with the following command:
Then, in a new terminal window, go to the folder where the code of your document is located (use the `cd` command) and generate your PDF with the following command:
```
$ pagedjs-cli index.html -o result.pdf
```
Some options to generate the PDF:
Some options to generate the PDF:
```-h, --help output usage information
-V, --version output the version number
......@@ -215,6 +174,3 @@ Some options to generate the PDF:
-e, --encoding [type] Set the encoding of the input html, defaults to "utf-8"
-t, --timeout [ms] Set a max timeout of [ms]
```
# 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.
![Transform flux into pages](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/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.
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
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 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.
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.
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.
The Paged.js library can be considered as a polyfill for the existing CSS modules - i.e., it is code that implements a feature on web browsers that do not support the feature. Note that this is our own interpretation of the implementation of this modules and, when the rules are implemented by browsers, they may differ.
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.
All you have to write the standardized CSS declarations and paged.js does its kind of magic. The library interprets the declarations and transforms them to other declarations that your browser understands, either by converting them to CSS styles that the browser does support or replacing them with JavaScript implementations.
The library is build in differents javascript parts that work together:
The library is build in differents Javascript parts that work together:
- the **chuncker** fragment the content into discrete pages,
- the **chunker** fragment the content into discrete pages,
- the **polisher** transforms the CSS declarations,
- and the **previewer** call the preview of your book in the browser.
- and the **previewer** creates the preview of your book in the browser.
## The Chunker: fragmenting the content
The chunker part of paged.js gets your styled content split into page chunks.
## The Chunker: fragment the content
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 has the size of your content area (i.e. page size minus the size of the margins). It tries to fit everything into this container and then looks for the overflowing content.
The chuncker part of paged.js getting your stylized content split into your page chunks.
![The chunker puts all your rendered content in a box and checks the overflow](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/images/chuncker-1.png)
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.
After that, the script creates a new box and puts the overflow content in it. Again, it looks for the next overflowing content.
![The chunker put all your rendered content in a box and check the overflow](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/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](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/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.
Paged.js does this repeatedly until the book is done. Once you’ve got your content chunked, you’ll need to repeat the process anytime something changes.
![The chunker creates a new box and puts the overflow content in it](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/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 using 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
Each content area is a CSS column independant from the other areas. Using columns allows the script to have easier access to the linked properties already implemented in browsers, such as breaks, element properties, or widows and orphans.
This doesn't prevent you from using the CSS column property in your content
## The Polisher: polyfilling 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.
With the polisher part, Paged.js also builds new boxes to create page layouts and and places your content boxes on these pages.
![](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/images/div-pages.png)
In parallel, the script reads your CSS file to have information about the print styles and transforms your `@page` rules into classes that your browser understand today. We use the CSS tree library to parse the CSS from text and replace `@page` rules with classes. The polisher also replaces calls such as running headers, page counters, or CSS generated content functions with variables from the DOM.
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.
Paged.js includes support for a lot of things from the CSS (generated content for) paged media specifications, so that you can write CSS that conforms to those specifications. Paged.js does the work of applying it on the transformed DOM.
Let's take the following CSS as an example:
```CSS
@page {
@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 {
......@@ -128,12 +99,10 @@ h1#title {
}
```
Paged.js transforms this into a CSS that is understandable to the browser:
Paged.js transforms this into CSS that is understandable to the browser:
```CSS
.pagedjs_page {
.pagedjs_page {
--pagedjs-string-title: "Moby Dick";
margin-top: 10mm;
margin-right: 20mm;
......@@ -142,18 +111,16 @@ Paged.js transforms this into a CSS that is understandable to the browser:
}
.pagedjs_page .pagedjs_margin-bottom-left::after {
content: string(title);
content: string(title);
}
.pagedjs_page .pagedjs_margin-bottom-center::after {
content: var(--pagedjs-string-title);
content: var(--pagedjs-string-title);
text-transform: uppercase;
}
```
This will apply to the transformed DOM (here simplified):
This will apply to the transformed DOM (this is a simplified version of what Paged.js generates):
```html
<div id="page-1" class="pagedjs_page">
......@@ -176,43 +143,20 @@ This will apply to the transformed DOM (here simplified):
</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.
## The Previewer: rendering the paginated document
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 builds the preview of your document in the browser, so you can see exactly how things are going to look and then adjust your content accordingly.
## The 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.
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 specify the delay before the paged.js script is launched. (We will see this in another part.) It is important to note that paged.js is just a script like other scripts, so you can use it however you want.
## DOM modifications
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.
It also adds references to every node (for example, it adds classes to differentiate right or left pages). This gives us complete control over the page layout without any hacks.
This documentation will specify for each CSS property the properties 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.
# Paged.js Interface
It is certainly easier to use paged.js with a rendering where you _actually_ see the pages of your book side by side. For this, you can directly style the `div` pages using classes.
It is certainly easier to use paged.js with a rendering where you *actually* see the pages of your book side by side. For this, you can directly style the `div` pages using there classes.
We provide you an exemple of CSS to do this in an easy way.
We have provided an example of CSS to do this in an easy way.
Download this CSS file: [interface-01.1](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/blob/master/ressources/interface-0.1.css)
Link the CSS file to your document:
```HTML
<link href="paht/to/file/interface-0.1.css" rel="stylesheet" type="text/css">
<link href="path/to/file/interface-0.1.css" rel="stylesheet" type="text/css">
```
You can uncomment and modify part of the CSS file:
In the CSS file you can uncomment and modify parts:
In the CSS file you can uncomment and modify parts:
- for recto/verso book
- to see and set the baseline
- to see and set the baseline
# Global Layout
- Print media query
- @page rule
* Print media query
* @page rule
- Page size property
- Margin size property
- Page spread or recto/verso
- Page breaks
- Crop marks and bleed
- Code resume of the chapter
* Page size property
* Margin size property
* Page spread or recto/verso
* Page breaks
* Crop marks and bleed
* Code resume of the chapter
## Print media query
The media queries allows you to target different media type and screen size. It's typically used in reponsive design to adapt and optimize your design according to the interface on which a reader will read your content.
The media queries allows you to target different media type and screen size. It's typically use in reponsive design to adapt and optimize your design according to the interface on which a reader will read your content.
Media queries can also be used to create your print styles using `@media print`.
Media queries can also be used to create your print styles using `@media print`.
The first thing to do in your style sheet is to specify this request:
```css
@media print {
/* All your print styles go here */
@media print {
/* All your print styles go here */
}
```
The styles declared in this media query will only be applied when the web page is printed from the browser print dialog to create a PDF. For example, the size of the typography for print is declared differently than that for screen display so it is more suitable for printing, or images are removed (with `display:none`) to save ink. Paged.js provides you a preview in the browser of the comportement of your styles when printing.
The styles declared in this media query will only be applied when the web page is printed from the browser print dialog to create a PDF. For example, the size of the type for print might be declared differently to that for screen display so it is more suitable for printing, or images might be removed (with `display:none`) to save ink. Paged.js provides you a preview in the browser of how your styles will appear when printing.
## @page rule
The @page rule lets you specify various aspects of your page model such as dimensions, orientation, background, margins, cropping, registration marks, and so on.
The @page rule lets you specify various aspects of your page model such as dimensions, orientation, background, margins, cropping, registration marks, and so on.
All the CSS properties that affect the gabarit of your page must be declared inside.
All the CSS properties that affect the layout of your page must be declared inside.
## Page size property
The `size` property specifies the size of your page (excluding bleeds). This fixed size can be declared by length units in centimeters (`cm`) millimeters (`mm`) or inches (`in`). The first number is the width of your document and the second number is the height. By default, paged.js uses the A4 size (210 × 297 mm).
The `size` property specifies the size of your page (without bleeds). This fixed size can be declared by length units in centimeter (`cm`) millimeter (`mm`) or inch (`in`). The first number is the width of your document and the second number is the height. By default, paged.js use the A4 size (210 × 297 mm).
The size property is declared inside the at-page rule:
The size property is declared inside the `@page` rule:
```Css
@page {
......@@ -62,26 +44,22 @@ The size property is declared inside the at-page rule:
}
```
### Page size and page orientation keywords
It's also possible to specify the page size by using some page size keywords. Optionnaly, they can be combined with page orientation keywords (`portrait` or `landscape`) to change the oprientation of the page (portrait by default).
It's also possible to specify the page size by using some page size keywords. Optionally, they can be combined with page orientation keywords (`portrait` or `landscape`) to change the orientation of the page (which is portrait by default).
```css
/* Use A5 paper */
@page {
size: A5;
@page {
size: A5;
}
/* Use A4 paper in landscape orientation */
@page {
size: A4 landscape;
@page {
size: A4 landscape;
}
```
**Page size keywords and their size**
| **Page size keyword** | **size** |
......@@ -101,213 +79,151 @@ It's also possible to specify the page size by using some page size keywords. Op
| legal | 8.5 × 14 in |
| ledger | 11 × 17 in |
### CSS variables
You can’t use CSS variables in this property because browsers do not support it. Unfortunately, the `@page { size }` property is the only thing we can't manage and we need to print (to generate the PDF).
You can’t use CSS variables in this property because browsers do not support it. Unfortunately, the `@page { size }` property is the only thing we can't polyfill that we need to print (to generate the PDF).
However, we create CSS variables from your declaration and use them in the previewer. You can therefore reuse them in your document if you need them for your calculations:
* `var(--pagedjs-pagebox-width)` for the width of your page
* `var(--pagedjs-pagebox-height)` for the height of your page
- `var(--pagedjs-pagebox-width)` for the width of your page
- `var(--pagedjs-pagebox-height)` for the height of your page
### Multiple page sizes
Your browser can only understand one page size for your document. If you want to create a document with different page sizes, you will need to create two separate HTML files and generate two PDFs.
## Margin size property
The margins of your pages are to be declared in the at-page rules with the same syntax you usually use for your other elements. Use length units like centimeter (`cm`) millimeter (`mm`), inch (`in`) or pixel (`px`).
The margins of your pages are to be declared in the `@page` rules with the same syntax you usually use for your other elements. Use length units like centimeters (`cm`) millimeters (`mm`), inches (`in`) or pixels (`px`).
```css
@page {
margin: 20mm 30mm;
margin: 20mm 30mm;
}
```
By default, the margins are set to 20mm.
Other exemple with different syntaxes:
Other examples with different syntaxes:
```css
/* All margins are 30mm */
@page {
margin: 30mm;
margin: 30mm;
}
/* Top and bottom margins are 3in,
left and right margins are 2in */
@page {
margin: 3in 4in;
margin: 3in 4in;
}
/* All margins are different */
@page {
margin-top: 20mm;
margin-bottom: 25mm;
margin-left: 10mm;
margin-right: 35mm;
margin-top: 20mm;
margin-bottom: 25mm;
margin-left: 10mm;
margin-right: 35mm;
}
```
## Page spread or recto/verso