Commit 1df8a0dc authored by Julie Blanc's avatar Julie Blanc

initial

parents
.DS_store
\ No newline at end of file
# FAQ
**CSS Variables doesn'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).
---
**Default fragmentation of paged.js**
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.
* Each `<section>` tag is preceded by a default page break,
* If an image don't have the place to fit in a page, it's push in 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).
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.
\ No newline at end of file
# Getting Started with Paged.js
## A quick presentation of paged.js
Paged.js is an open-source javascript library to display paginated content in the browser and to generate print books using web technology.
It's composed of a *Chuncker* and a *Polisher*. The Chunker chunks up a document into paged media flows and applies print classes. The Polisher converts @page css to classes, and applies counters and content.
### 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/)
### 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
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/
## 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:
* your usual html and css files,
* the paged.js script,
* a (local) server,
* a web browser.
### Access to paged.js script
**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>
```
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
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:
```HTML
<script src="js/paged.polyfill.js"></script>
```
**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):
```
$ 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>
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. 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).
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 `http://localhost:8888`
### 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**.
#### 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):
- Chromium
- Google Chrome
- Brave
- Opera
We know that many of you are attached to Mozzila Firefox, 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).
#### 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 only. 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.
## Generating a PDF
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).
### Option 1: with a browser
1. Simply click on the “Print” button of your browser.
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.
### Option 2: with pagedjs-cli
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
```
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:
```
$ pagedjs-cli index.html -o result.pdf
```
Some options to generate the PDF:
```-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]
```
# Paged.js documentation
## Getting Started with Paged.js
- A quick presentation of paged.js
- W3C specifications
- A community
- Running paged.js
- Access to paged.js script
- Use a local server
- Which browser to use?
- Generating a PDF
- Option 1: with a browser
- Option 2: with pagedjs-cli
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment