Commit e88b1be3 authored by julientaq's avatar julientaq
Browse files

first layout

parents
Pipeline #367 failed with stages
in 4 seconds
node_modules
.vscode
[submodule "themes/ananke"]
path = themes/ananke
url = https://github.com/budparr/gohugo-theme-ananke.git
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
# This is the first test
How is it going?
Ex laboris consequat mollit Lorem ex enim ea sint anim. Ex laboris consequat mollit Lorem ex enim ea sint anim.Ex laboris consequat mollit Lorem ex enim ea sint anim.Ex laboris consequat mollit Lorem ex enim ea sint anim.Ex laboris consequat mollit Lorem ex enim ea sint anim.Ex laboris consequat mollit Lorem ex enim ea sint anim.Ex laboris consequat mollit Lorem ex enim ea sint anim.
\ No newline at end of file
baseURL = "http://example.org/"
languageCode = "en-us"
title = "pagedjs, house of HTML printing"
theme = "pagedjs"
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[menu]
[[menu.main]]
identifier = "blog"
name = "Journal"
url = "/posts/"
weight= 2
[[menu.main]]
identifier = "documentation"
name = "Documentation"
url = "/documentation/"
weight= 2
[[menu.main]]
identifier = "code"
name = "Code of Conduct"
url = "/codeOfConduct/"
weight= 3
[[menu.main]]
identifier = "colophon"
name = "Colophon"
url = "/colophon.html"
weight= 4
---
title: "welcome!"
subtitle: "this is the subtitle"
class: "homepage"
colorPaper: "whitesmoke"
baseline: "the library that prints the web"
header: "this is fun"
---
<!-- {{< pagedjs-logo class="content-logo" >}} -->
<!-- ## The js library that prints the web -->
<!-- --- -->
<!-- {{< halftone src="img/intro.jpg" title="The house of printing sun" id="test">}} -->
{{<img class="print-machine" src="img/1139e889a554ab3a295840.jpg">}}
**paged.js** is an open source and free library to paginate content in the browser, to turn webpages in beautiful PDF. If it's your first encounter with the project, you may want to [read a bit about how it came to life](about). You may also want to [test the library in our Codepen](codepen) or [follow the documentation](doc).
Or maybe, you want to read the [latest news](blog/) around paged.js and CSS print.
---
title: "Code"
date: 2019-11-01T00:08:22+01:00
draft: true
---
# Code of conduct
Paged.js is a community project run by the Cabbage Tree Labs.
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at pagedjs@cabbagetreelabs.org. All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of actions.
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the project community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.
---
title: "Colophon"
date: 2019-10-23T17:26:17+02:00
draft: true
footer: true
---
---
title: "Colophon"
date: 2019-10-23T17:25:43+02:00
draft: true
---
# Colophon
Paged.js logo was designed by Anton Moglia and Julie Blanc in a train back from Les Rencontres de Lure.
Minipax, the extraordinary font used on the website was designed by Raphaël Ronot and is exclusively offered trhough [Velvetyne type foundry](http://www.velvetyne.fr)
Paged.js website was designed and built by [Julien Taquet](mailto://julien@lesvoisinsdustudio.ch) thanks to the amazing Hugo static website generator.
Paged.js is maintained by the nice folks at [Cabbage Tree Labs](https://www.cabbagetreelabs.org).
---
title: "Getting Started with Paged.js"
date: 2019-09-03T18:23:22+02:00
draft: true
part: 1
layout: doc-single
menu: "documentation"
weight: 1
intro: "in this section, you'll see what paged.js is about and how you can use all the powers of HTML and CSS to make great book"
cover: "images/chuncker-1.png"
---
## 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.
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.
### W3C specifications
<p>Paged.js is based on the CSS standards written by the World Wide Web Consortium (W3C). It acts like a sort of <span class="dt">polyfill<span class="dd">A <a href="https://en.wikipedia.org/wiki/Polyfill_(programming))">polyfill</a> is code that implements a feature on web browsers that do not support the feature</span> </span>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.</p>
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 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:
- your usual html and css files,
- the paged.js script,
- a (local) server,
- a web browser.
### Access to paged.polyfill.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 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 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. 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: Development version**
To get set up with the development 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. 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. 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 perfectly with all the browsers around, but some are more suitable than others. It depends on the features you want to have for your documents (CSS flexbox, hyphens…). But you also maybe need a browser that take into account the size property to generate PDFs. Here are some explanations to help you choose.
#### Support of @page { size }
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. These property is only supported in some browsers:
- Chromium
- Google Chrome
- Brave
- Opera
We know that many of you are attached to Mozilla Firefox (and so are we). It is still possible to use paged.js with 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
#### 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 transforms your content so that it can be viewed in a browser. PDF generation can be done in two ways:
- 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. 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”.
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 (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):
```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs-cli.git
$ cd pagedjs-cli
$ npm install -g pagedjs-cli
```
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:
```-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]
```
---
title: "How paged.js works"
date: 2019-09-03T18:23:22+02:00
draft: true
part: 2
layout: doc-single
weight: 2
menu: "documentation"
intro: "Implementing CSS for the print is not an easy task. Here is an overview of what Paged.js is doing without you being aware of that."
---
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/raw/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.
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 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.
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 **chunker** fragment the content into discrete pages,
- the **polisher** transforms the CSS declarations,
- 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.
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 chunker puts all your rendered content in a box and checks the overflow](https://gitlab.pagedmedia.org/tools/pagedjs-documentation/raw/master/images/chuncker-1.png)
After that, the script creates a new box and puts the overflow content in it. Again, it looks for the next overflowing content.
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/raw/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 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 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/raw/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.
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 {
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 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 (this is a simplified version of what Paged.js generates):
```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.
## 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.
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, 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.
---
title: "Paged.js Interface"
date: 2019-09-03T18:23:22+02:00
draft: true
part: 3
weight: 3
layout: doc-single
menu: "documentation"
---
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.
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="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:
- for recto/verso book
- to see and set the baseline
---
title: "Global Layout"
date: 2019-09-03T18:23:22+02:00
draft: true
part: 4
layout: doc-single
intro: "If you want to start designing your own book, now is the perfect time!"
menu: "documentation"
weight: 4
---
<!--