Part01_Getting-Started-with-paged.md 9.63 KB
Newer Older
Julie Blanc's avatar
Julie Blanc committed
1 2
# Getting Started with Paged.js

3
## A quick introduction of paged.js
Julie Blanc's avatar
Julie Blanc committed
4

5
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.
Julie Blanc's avatar
Julie Blanc committed
6

7
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.
8 9 10 11 12

### 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.

13
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.
Julie Blanc's avatar
Julie Blanc committed
14 15 16

### W3C specifications

17
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.
18

19
(\*) A [polyfill](<https://en.wikipedia.org/wiki/Polyfill_(programming)>) is code that implements a feature on web browsers that do not support the feature.
20

21
W3C CSS modules implemented by paged.js :
22

23 24 25
- [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/)
26

Julie Blanc's avatar
Julie Blanc committed
27 28 29 30 31 32
### A community

The code of paged.js is open-source with a MIT license and the development is community-driven. Everyone is invited to join us!

You can find the source code of paged.js on the repo of our self-healing gitlab: https://gitlab.pagedmedia.org/tools/pagedjs

33
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/
Julie Blanc's avatar
Julie Blanc committed
34

35
## Running paged.js
Julie Blanc's avatar
Julie Blanc committed
36

37
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:
Julie Blanc's avatar
Julie Blanc committed
38

39 40 41 42
- your usual html and css files,
- the paged.js script,
- a (local) server,
- a web browser.
Julie Blanc's avatar
Julie Blanc committed
43

44
https://www.startpage.com/fr/
Julie Blanc's avatar
Julie Blanc committed
45

46
### Access to paged.polyfill.js script
Julie Blanc's avatar
Julie Blanc committed
47 48 49 50 51 52 53 54 55

**Option 1: CDN version**

You can use the hosted version of the script, just copy this in the `head` of your document:

```HTML
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
```

56
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.
Julie Blanc's avatar
Julie Blanc committed
57

58
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:
Julie Blanc's avatar
Julie Blanc committed
59 60 61 62 63

```HTML
<script src="js/paged.polyfill.js"></script>
```

64
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.
Julie Blanc's avatar
Julie Blanc committed
65 66 67

**Option 2: Developpement version**

68
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):
Julie Blanc's avatar
Julie Blanc committed
69 70 71 72 73 74 75 76 77 78 79 80

```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs.git
$ cd pagedjs
$ npm install
$ npm start
```

Link the script with your document:

<script src="http://localhost:9090/dist/paged.polyfill.js"></script>

81
All you need to know about setup, development and testing with the local dev-server is available in the README.md of the repo.
Julie Blanc's avatar
Julie Blanc committed
82 83 84

### Use a local server

85
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).
Julie Blanc's avatar
Julie Blanc committed
86

87
You can find all the documentation on their respective websites. Broadly, what you need to do is:
Julie Blanc's avatar
Julie Blanc committed
88

89 90 91 92
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`).
Julie Blanc's avatar
Julie Blanc committed
93

94
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.
Julie Blanc's avatar
Julie Blanc committed
95 96 97

### Which browser to use?

98
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**.
Julie Blanc's avatar
Julie Blanc committed
99

100
#### Support of @page { size }
Julie Blanc's avatar
Julie Blanc committed
101

102
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:
Julie Blanc's avatar
Julie Blanc committed
103 104 105 106 107 108

- Chromium
- Google Chrome
- Brave
- Opera

109
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.
Julie Blanc's avatar
Julie Blanc committed
110 111 112

#### Support of CSS grid

113
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
Julie Blanc's avatar
Julie Blanc committed
114 115 116

#### Different rendering between browsers

117
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.
Julie Blanc's avatar
Julie Blanc committed
118

119
We recommend staying on the same browser and OS for the design and generation of the PDF to avoid unpleasant surprises.
Julie Blanc's avatar
Julie Blanc committed
120 121 122

## Generating a PDF

123
Paged.js transforms your content so that it can be viewed in a browser. PDF generation can be done in two ways:
Julie Blanc's avatar
Julie Blanc committed
124

125 126
- 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).
Julie Blanc's avatar
Julie Blanc committed
127 128 129

### Option 1: with a browser

130
1. Click on the “Print” button of your browser.
Julie Blanc's avatar
Julie Blanc committed
131

132
2. Change the _Destination_ to "Save as a PDF file”.
Julie Blanc's avatar
Julie Blanc committed
133 134

3. In the avanced settings:
135 136 137
   - Set _Margins_ to “none”,
   - Remove the option “Headers and footers”,
   - Select the option “Background graphics”.
Julie Blanc's avatar
Julie Blanc committed
138

139
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.
Julie Blanc's avatar
Julie Blanc committed
140 141 142

### Option 2: with pagedjs-cli

143
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.
144

Julie Blanc's avatar
Julie Blanc committed
145 146 147 148 149 150 151 152
First, download and install pagedjs-cli with your terminal (you need to have git and npm installed):

```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs-cli.git
$ cd pagedjs-cli
$ npm install -g pagedjs-cli
```

153
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:
Julie Blanc's avatar
Julie Blanc committed
154 155 156 157 158

```
$ pagedjs-cli index.html -o result.pdf
```

159
Some options to generate the PDF:
Julie Blanc's avatar
Julie Blanc committed
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176

```-h, --help                  output usage information
-V, --version               output the version number
-i, --inputs [inputs]       Inputs
-o, --output [output]       Output
-d, --debug                 Show Electron Window to Debug
-l, --landscape             Landscape printing
-s, --page-size [size]      Print to Page Size [size]
-w, --width [size]          Print to Page Width [width]
-h --height [size]          Print to Page Height [weight]
-m, --page-margin [margin]  Print with margin [margin]
-n, --hyphenate [lang]      Hyphenate with language [language], defaults to "en-us"
-hi, --hypher_ignore [str]  Ignore passed element selectors, such as ".class_to_ignore, h1"
-ho, --hypher_only [str]    Only hyphenate passed elements selector, such as ".hyphenate, aside"
-e, --encoding [type]       Set the encoding of the input html, defaults to "utf-8"
-t, --timeout [ms]          Set a max timeout of [ms]
```