News from paged.js!

Successfully published @pagedjs/paged-page

2025-11-07T00:00:00Z

Well, you know November has come
When it's gone away

Gorillaz, November has come

Sorry for the silence, november came and with it, all the slowness of winter, which, this year, got the form of a quite strong covid. The good thing is that it’s now away, and i’m back up and running, and it’s the perfect moment to announce one of the great wins for paged.js rebuilding session we’re hard working for.

The benefits of a cssPrint preview

As far as i remember, i always used the browser to generate books using CSSPrint. I never got the hard experience of generating a PDF through the command line, to check the result and tweak the content, to do it again, and again.
I got the luxury of getting into cssPrint using book.js, a project founded by Adam Hyde (like paged.js) that was using CSS Regions to generate page. You made a change on page 2, and all the book was rebuilding from there. And we could quickly try things using the inspector and everything was visible on screen. But CSS Regions were drop by the Chromium team and what was amazing just disappeared. So we didn’t update Chrome for quite a while. And WebKit followed, and everything about CSS regions disappeared.

I ended up using a very precise Chromium under a very special Ubuntu version under a virtual machine for a long time (and we didn’t have SSD then, everything was so long). And i wasn’t the only one strugglin, even the folks at Open Source Publishing ended up making their own fork on webkit to support their design work. We, designers, love to experiment with our tools, and the browser is one of the most accessible setup for that. We need to make a poster? We’re gonna build our own system for previewing on screen what our HTML and CSS will render. And to do so, we spend quite a long time to figure out the HTML and CSS that will allows us to see what we’re gonna print.

But most of the time, this html and this css is litterally a simplest version of what paged.js generate to look at it on a screen. We have a <div> that will be the page, and that will have a CSS to handle the preview of the screen: setting the size of the <div> to be equal to what you’ll set in the @page, make sure to set the overflow accordingly, and, if you really want to reuse the system, you’re setting up a precise CSS grid, with margins, space for running head, etc.

And by the game of copy/pasting, we’re rebuilding the same thing every time we need, and it’s not fun, because we always forget a line, or get into a new bug, because copy and pasting is far from free of errors.

That’s why, when we decided to update paged.js, we decided that any bit of the library that could be reused outside will be made available as such. Today, we’re releasing the first block of this, the <paged-page> component.

But hey, what is a web-component?

HTML is made of standard tags that we all share from one web page to another. <h1> is a level one title, <p> is a paragraph and <figure> an element that will be understood by readers and computers, as a figure. Those tags come with attributes (like id or class for the most well known ones), and a behavior that has been defined by the W3C, and implemented in a similar way in all the browsers. A good example? an <img> tag has a alt attribute. This attribute give an opportunity to the author to add a description of the image that will be picked up by a screen reader and read aloud to, for example, a person with visibility issues. This behavior is described in the specs, and give some rules on how an element will work.

A web-component is a set of techonologies allowing author to write their own component.

Using javascript, a web-component will include the HTML structure (the template), the CSS (the default styles), and their own behavior (how the element will react to a user). And to use it, you’ll only need the javascript file that define all those, and then you can simply add the component where you need in your webpage.

One of my favorite web-component is a preview of a keybaord called x-keyboard (and its source). It’s the perfect tool to show a keybaord layout on the screen, and it will even be able to pick up what the visitor will type to and react accordingly.

So paged-page is a web-component to show the preview of a printed page on the screen, following the W3C instructions used for printing.

You want to print a page with a huge text in the middle of your page?

This is the HTML you’ll write:

<paged-page><h1>The store will be closed for Christmas. See you in January!</h1></paged-page>

All the CSS for the preview, and for the print, comes with the component. This is already a win.

And we’ve been a bit further, and added attributes to handle all the needed CSS directly from the HTML element: bleed, marks, margin, width and height are added as attributes and transfered to the CSS and the HTML.

A good thing with a web-component, is that it can be transformed with CSS quite easily: you only need to do what you would do with a classic HTML tag, like this:

paged-page#id {
    padding: 3em;
    background: green;
}

…and you’re done, your page has now a padding of 3mm and a green background.

Pretty easy, right? I hope you’re gonna enjoy this, we’re really excited with the possibility this will offer.

Cascading pages or how I learned to style the content inside the page

Conceptually, in the word of web to print, the sheet of paper doesn’t impact the layout of its content (outside of what the @page can do): in short, you can’t define how the content of the page look depending on the type of page it’s on.

A simple example: let say that your design needs to have the text on the thirteenth page in another color and you don’t know before hand what would be on this page, you would asssume that you could use the following code:css

@page:nth(13) {
  .funny-text {
    color: green;
  }
}

Well, you can’t. Because the specs does not allow anything not page related on the @page. You can have margins, bleeds, marks and set the geometry of the page with the size property, but that’s it.

Because this would create a cascade issue: what if somewhere else in your CSS, you write this

.funny-text {color:yellow}`

What color would be your text?

And then, think of all the weird thing you could do with text-size: if the text needs to be huge on page 10, but making it huge push it to page 11, what should you have on the page 10 then?

Well, paged.js has a weird answer to that issue, because of the transformation it makes on the css stylesheet. You see, any @page:nth(13) selector is transformed into a class: @page become div.paged_page.paged_nth_13 which totally accepts nested CSS, and therefore, will have no trouble with styles for the children of that page, and the specificity rules will be quite clear.

I’m calling this the quantum cascade: it is and it is not, until it’s appearing on the page you’ll print in the end.

But it’s a bit of a lucky game, because sometimes, you don’t want that to happen, and your stuck with this not-a-bug-a-feature that paged.js offers. Thankfully, in the world of web component, it’s a bit different. Picture this HTML

    <paged-page
      id="page-12"
      name="id-of-the-page2"
      width="100mm"
      height="100mm"
      bleed="5mm"
      margin="8mm 14mm"
      marks="cross crop"
    >
      <h2>This is a regularly sized page.</h2>
      <p> there will be some content here.</p>
    </paged-page>

If I want to change the color of the text, and add this CSS:

  #page-12 {
    background: green;
      h2 {
          color: blue;
      }
  }

As you can see the component is almost invisible, and you can easily change the content following the classic cascade.

But maybe i want to change the style of the page-area, then we need to make the component visible. That’s what the ::part pseudo elements is for.

#page-12::part(page-area) {
        background: yellow;
}

This could seem not that useful, because right now, we’re only talking about paged-area, but as soon as you get margins in, it becomes extremely powerful because you can target very deep css with a simple shortcut:

#page-12:part(bottom-center) { text-transformation: uppercase; font-size: .8em}
#page-12:part(bottom-right)::after {content: counter(page)}

A recap

<paged-page> is a component that is waiting for those attributes:

width: the width of the page (without bleed)
height: the height of the page (without bleed)
bleed: the amount of bleed. (right now, you can’t have custom bleeds per side, but we’re thinking about it)
margin: the margins of the page, written down exactly as their css counterpart.
marks: the crop marks and cross marks you can add to the page

And since it’s HTML, you can add any property you’d need for your own code. For example, paged.js will add data-paged-ref to support the page break system.

The component itself is made of three elements:

the page-marks: for bleed and marks.
the paged-margins: allowing for quick access to margin-boxes using the paged-margins webcomponent.
the page-area: where the content of the component will appear.

If you happen to have multiple page with multiple page size, save as PDF will create a PDF with different page size.

About margins

Since we were quite happy with the paged-margins, we got into exploring margin-boxes as web-components. As you may know, in the land of CSSPrint, the page has a limited of places where you can add things in the margins. THe specifications say that there are 17 margin-boxes, following this diagram:

As you can see, the place you can add content is quite limited, and the geometry will be dependant on what you’ll have in there. It’s one of the thing we never make when we do HTML+CSS for printing, without using pagedjs or other things. We just don’t bother adding them, and we end up adding some content with a position absolute on each page, because more is too much.

But if the preview of your page can have those margins, you may consider using them, and if they are needed for paged.js we added them, and it’s pretty easy to bring them up:


<paged-page>
    <paged-margins slot="page-margins">
        <paged-margin-content slot="top-left">Does this appear?</paged-margin-content>
        <paged-margin-content slot="top-right">Should have</paged-margin-content>
        <paged-margin-content slot="left-top">T</paged-margin-content>
    </paged-margins>

    <h2>there are margin everywhere !</h2>
</paged-page>

In that HTML, we have a page, that contains the margins, and the rest of the content will fill up the page-area.

We hope you gonna love playing with it, we’re already pretty much excited to put that into paged.js!

wanna test it quickly? Include that script to your HTML and start making things!

<script
      type="module"
      src="https://unpkg.com/@pagedjs/[email protected]/dist/PagedPreview.js"></script>

On a side note, we got an issue for some translation of the documentation, and spanish may be the next language for paged.js documentation!

¡Vale!

la preview des pages, avec ou sans paged.js

2025-11-07T00:00:00Z

Well, you know November has come
When it's gone away

Gorillaz, November has come

Bonjour tout le monde, j’espère que vous allez bien.

Pardon pour le silence, novembre est là et avec lui la lenteur de l’hiver, qui, cette année, a pris la forme d’un covid assez costaud. La bonne nouvelle, c’est que j’en ai fini avec lui pour cette année, on reprend le travail et c’est le moment parfait pour annoncer une chouette avancée dans notre travail de reconstruction de paged.js. Mais avant de plonger dedans, un petit peu de pourquoi.

Les bénéfices d’une prévisualisation cssPrint

Je suis un chanceux, par ce que j’ai toujours utilisé le navigateur pour générer des livres avec CSSPrint. Je n’ai jamais connu l’expérience laborieuse de générer un PDF en ligne de commande, de vérifier le résultat, de retoucher pour régénérer, encore et encore.

J’ai eu le luxe d’aborder cssPrint via book.js, un projet fondé par Adam Hyde (comme paged.js) qui utilisait les CSS Regions pour générer les pages. Vous faisiez un changement à la page 2, et tout le livre se reconstruisait à partir de là. Et on pouvait tester rapidement toute nouvelle idée improbable grâce à l’inspecteur, tout était visible à l’écran. Mais les CSS Regions ont été abandonnées par l’équipe de Chromium, puis WebKit a suivi, et tout ce qui concernait les CSS Regions a disparu.

J’ai dû utiliser une version très précise de Chromium, qui tournait sous une version très particulière d’Ubuntu dans une machine virtuelle sur un mac en galère pendant (trop) longtemps (et à l’époque, nous n’avions pas de SSD, tout était tellement lent).

Et j’étais pas le seul à galérer : même l’équipe d’Open Source Publishing a fini par créer leur propre fork de WebKit pour soutenir leur travail de design graphique.

Nous, designers, aimons expérimenter avec nos outils, et le navigateur est l’un des environnements les plus accessibles pour ça. Besoin de faire une affiche ? On va construire notre propre système de prévisualisation à l’écran pour s’assurer que le print corresponde à ce qu’on a en tête. Et pour y parvenir, on passe beaucoup de temps à reproduire une page à l’écran (et prête à être imprimée).

Mais la plupart du temps, cet HTML et ce CSS sont littéralement une version simplifiée de ce que paged.js génère pour l’affichage à l’écran: on crée un <div> qui représente la page, avec du CSS pour gérer la prévisualisation : on donne à ce <div> la taille définie dans le @page, on règle l’overflow, et si on veut vraiment réutiliser le système, on définit une grille CSS précise (mais qu’on ne réutilise jamais vraiment).

Et à force de copier/coller, on reconstruit la même chose à chaque fois qu’on en a besoin, et c’est pas très marrant, parce qu’on oublie toujours une ligne ou on tombe sur un nouveau bug et on passe du temps à gérer des galères d’oubli là ou on devrait apprécier un moment de design.

Quand on a décidé de mettre à jour paged.js, il était évident que chaque morceau du programme pouvant être réutilisé à l’extérieur serait rendu disponible tel quel. Aujourd’hui, nous publions le premier bloc : le composant web .

Mais au fait, c’est quoi un web-component ?

HTML est fait de balises standards que l’on partage tous d’une page web à l’autre, comme un langage commun. <h1> est un titre de niveau 1, <p> un paragraphe, et <figure> un élément qui sera compris par les lecteurs d’écran comme une figure. Ces balises ont des attributs (par exemple id ou class, les plus connus) et un comportement défini par le W3C et implémenté de façon similaire dans les navigateurs. Par exemple : une balise <img> possède un attribut alt. Cet attribut permet à l’auteur de fournir une description de l’image, qui sera lue par un lecteur d’écran à une personne malvoyante. Ce comportement est décrit dans les spécifications, avec des règles sur la manière dont l’élément doit fonctionner.

Un web-component est un ensemble de technologies permettant aux auteurs d’écrire leurs propres element HTML.

En utilisant un simple fichier .js, un web-component regroupe sa structure HTML (le template), son CSS (les styles par défaut) et son comportement (s’il a des intéractions, ce qu’il doit rajouter au html ou tout autre idée encapsulable dans un élément HTML). Et pour l’utiliser, on inclut ce fichier dans une balise script dans notre HTML et voilà, on peut utiliser le web-component.

L’un de mes web-components préférés est une prévisualisation de clavier: x-keyboard (source). C’est l’outil parfait pour afficher une disposition de clavier à l’écran, et il peut même réagir aux touches réellement tapées par le visiteur.

paged-page est donc un web-component destiné à afficher la prévisualisation d’une page imprimée à l’écran, en suivant les instructions W3C utilisées pour l’impression.

Vous voulez imprimer une page avec un énorme texte au milieu ? Voici le HTML à écrire (je vous laisse le plaisir de choisir le CSS pour centre le texte, il y a trop de solutions possibles, on n’est plus en 2002).

<paged-page><h1>Le magasin sera fermé pour Noël. À l’année prochaine !</h1></paged-page>

Tout le CSS nécessaire à la prévisualisation et à l’impression est inclus dans le composant. Plus besoin de passer trop de temps à retrouver la dernière bonne version.

Et nous sommes allés un peu plus loin en ajoutant des attributs pour gérer directement depuis le HTML tout le CSS nécessaire (que l’on trouverait normalement dans un @page) : bleed, marques, marges, largeur et hauteur sont ajoutées en attributs puis transmises au CSS et au HTML.

L’un des avantages d’un web-component, c’est qu’il peut être stylé très facilement : il suffit de faire ce que vous feriez avec une balise HTML classique :

paged-page#id {
    padding: 3em;
    background: green;
}

…et voilà, votre page a maintenant un padding de 3 mm et un fond vert.

Plutôt facile, non ? J’espère que vous allez aimer ça, nous sommes vraiment enthousiastes quant aux possibilités que cela va offrir.

Pages en cascade, ou comment j’ai appris à styliser le contenu à l’intérieur de la page

Conceptuellement, dans le monde du web-to-print, la feuille de papier n’impacte pas la mise en page de son contenu (à part ce que @page peut faire) : en bref, vous ne pouvez pas définir le style du contenu d’une page selon le type de page sur lequel il se trouve.

Un exemple simple : supposons que votre design impose que le texte de la treizième page soit d’une autre couleur, sans savoir à l’avance ce qui se trouvera sur cette page. Vous pourriez imaginer écrire :

@page:nth(13) {
  .funny-text {
    color: green;
  }
}

Eh bien, vous ne pouvez pas. Parce que les spécifications n’autorisent que des propriétés liées à la page dans @page. Vous pouvez définir les marges, le bleed, les marques, la taille de la page… mais pas le style de son contenu.

Car cela créerait un problème de cascade : imaginez qu’ailleurs dans votre CSS vous écrivez :

.funny-text { color: yellow }

De quelle couleur serait votre texte ?

Et imaginez les bizarreries possibles avec la taille du texte : si le texte doit être énorme sur la page 10, mais qu’en devenant énorme il passe à la page 11, que doit-il y avoir sur la page 10 ?

Eh bien, paged.js propose une réponse un peu étrange, liée aux transformations qu’il applique aux styles. Tout @page:nth(13) est transformé en classe : @page devient div.paged_page.paged_nth_13, qui accepte le CSS imbriqué et ne pose donc aucun problème pour styliser les éléments enfants, avec une spécificité claire.

J’appelle ça la cascade quantique : ça existe et ça n’existe pas, jusqu’au moment où ça apparaît dans la page finale.

Mais c’est parfois un jeu de hasard : parfois, vous ne voulez pas que ça arrive, et vous restez coincé avec cette fonctionnalité-qui-n’est-pas-un-bug. Heureusement, dans le monde des web-components, c’est différent. Regardez ce HTML :

<paged-page
  id="page-12"
  name="id-of-the-page2"
  width="100mm"
  height="100mm"
  bleed="5mm"
  margin="8mm 14mm"
  marks="cross crop"
>
  <h2>Ceci est une page de taille normale.</h2>
  <p> il y aura un peu de contenu ici.</p>
</paged-page>

Si je veux changer la couleur du texte, j’ajoute ce CSS :

#page-12 {
    background: green;
    h2 {
        color: blue;
    }
}

Comme vous le voyez, le composant est quasiment invisible : on peut styliser le contenu via la cascade classique.

Mais peut-être que je veux modifier le style de la zone de page elle-même. Dans ce cas, il faut rendre le composant visible. C’est justement le rôle du pseudo-élément ::part.

#page-12::part(page-area) {
    background: yellow;
}

Ça peut sembler anecdotique, parce qu’ici on parle seulement de page-area, mais dès que vous avez des marges, cela devient extrêmement puissant : vous pouvez cibler très profondément dans la structure avec un simple raccourci :

#page-12::part(bottom-center) { text-transform: uppercase; font-size: .8em }
#page-12::part(bottom-right)::after { content: counter(page) }

Récapitulatif

<paged-page> est un composant qui attend les attributs suivants :

width : largeur de la page (hors bleed)
height : hauteur de la page (hors bleed)
bleed : la quantité de bleed (pour le moment, pas encore de valeurs différentes par côté)
margin : les marges, écrites exactement comme leur équivalent CSS
marks : les marques de coupe et de repérage à ajouter

Et puisqu’il s’agit de HTML, vous pouvez ajouter n’importe quel attribut utile à votre code. Par exemple, paged.js ajoutera data-paged-ref pour gérer les sauts de page.

Le composant contient trois éléments :

les page-marks : pour le bleed et les marques ;

les paged-margins : pour accéder rapidement aux margin-boxes via le web-component `paged-margins`` ;

la page-area : où apparaît le contenu du composant.

Si vous avez plusieurs pages avec plusieurs tailles, l’enregistrement en PDF créera un PDF multi-format.

Notez que dans ce cadre, il n’est plus nécessaire d’ajouter le @page au css, puisque tout est fabriqué par le composant HTML.

À propos des marges

Et tant qu’à avoir la page, on s’est dit, pourquoi pas ajouter les marges, et en faire des web-componants. Comme vous le savez peut-être, dans CSSPrint, il existe 17 emplacements pour intégrer des contenus dans les marges sur une page:

Les trois quarts du temps, quand on n’utilise pas paged.js, on ne prend pas le temps d’ ajouter les margins-boxes. On finit par utiliser du position: absolute dans notre CSS, sur chaque page, pour aller au plus vite.

Mais si la prévisualisation de votre page inclut les marges par défaut, alors il devient facile de les utiliser. Et comme elles sont nécessaires pour paged.js, on les a ajouter au composants (ou plus exactement, on a fabriqué d’autres composants).

<paged-page>
    <paged-margins slot="page-margins">
        <paged-margin-content slot="top-left">le texte courant en haut à gauche</paged-margin-content>
        <paged-margin-content slot="top-right">en haut à droite</paged-margin-content>
        <paged-margin-content slot="left-top">dans la zone le plus haut de la marge de droite.</paged-margin-content>
    </paged-margins>

    <h2>il y a des marges partout !</h2>
</paged-page>

Ici, nous avons une page contenant des marges, et le reste du contenu remplit la page-area.

Comme souvent c’est le genre d’outil qui s’apprend en essayant. (dans les semaines qui viennent on va faire pas mal d’exemples, mais tout est là pour que vous puissiez commencer à essayer).

Nous espérons que vous allez adorer jouer avec ça ! (et qu’on puisse très vite intégrer tout ce boulot à paged.js)

Vous voulez tester rapidement ? Ajoutez simplement ce script à votre HTML et allez commencer à tester des trucs, et n’oubliez pas de venir nous dire comment ça s’est passé pour vous!

    <script
      type="module"
      src="https://unpkg.com/@pagedjs/[email protected]/dist/PagedPreview.js"
    ></script>

Oh un truc qui n’a rien avoir, mais AntonioJesusBlanco s’est proposé pour traduire la documentation existante en espagnol, et la branche git est prête. https://github.com/pagedjs/pagedjs/issues/310

venez participer si vous le souhaitez!

À très vite.

Documenting the update of the documentation

2025-10-16T00:00:00Z

Folks, today is a big day.

We managed to put some time into making a real developper’s documentation using jsdocs comments directly inside the code.

As you may have seen, we now have an updated eleventy with a great multilang setup. Where we can switch from one lang to another, and we can actually get new languages quite easily.

And better, we have a setup that will let you add issues, and commits to help us translate (which is, i think, one of the best contribution a project can get.)

On the developper’s world, i spent some time adding some jsdocs comments to paged.js and setup the script to generate the new documentation pages when a feature is added.

It’s not perfect yet (as Fred needs to read the exising docs to make sure the comments make sense), but the whole mechanism exists, and it’s really cool to see it working that way. wink wink

If you want to contribute, you can actually join us, fork the repo and add features and comments to the code.

I’ll come back very soon with some news about Paged.js work around CSS parsing.

talk soon!

En documentant la mise à jour de la documentation

2025-10-16T00:00:00Z

Aujourd'hui est un grand jour.

D’abord parce que c’est un vendredi et que demain, c’est week-end.

Ensuite par ce qu’on a pu avancé sur les questions de documentation de paged.js

Mais une chose à la fois.

Comme vous l'avez peut-être vu, nous avons maintenant une mise à jour du site fait avec eleventy (mais c’est tellement bien 11ty), qui est maintenant configuré pour faire du multi langues.

Pour l’instant on écrit en français et en anglais par ce que c’est ce qu’on connaît, mais il est très simple de rajouter d’autres langues à la volée et si vous voulez participer, contacter nous [email protected]

Pour nos amis développeurs, j'ai passé un moment pour ajouter des commentaires jsdocs à paged.js. Et à configurer le script pour générer une mise à jour de la documentation quand une fonctionnalité est ajoutée.

C’est pas encore parfait (j’attends que Fred puisse lire mes lignes pour s'assurer ensemble que je ne raconte pas n’importe quoi dans les parties les plus obscures du code), mais tout le mécanisme existe. clin d’œil

Si vous voulez contribuer, vous pouvez nous rejoindre sur le github, ou nous envoyer un mail ([email protected]">[email protected]).

À très vite.

Kickstarting the next iteration of Paged.js

2025-09-16T00:00:00Z

Last week, the paged.js core team kickstarted the work on the next version of paged.js.

While Fred stayed in California, Gijs and I were in the office of Open Source Publishing (OSP) in Brussels, where we did quite a lot of things around the future of paged.js.

For those who are discovering the world of CSS Print, a couple words about OSP. They are a collective who have been making books and printed stuff using the technologies of the web for a very long time. Such a long time that they even knew CSS-Regions, and even have their own web-kit implementation to support their practices and work.

Each member of OSP has been an inspiration and Paged.js wouldn’t be what it is today, if it weren’t for the love and energy they’ve put in the craft. If you don’t know what i’m talking about, a simple glance at the osp.kitchen website will give you a good example of where you could find inspiration.

I really like the symbol that paged.js neue starts there. Thank you for sharing your office with us.

So let’s not spend more time, and let’s get into it.

A quick recap of what’s on the road map.

As you may remember, Chrome is now supporting a subset of paged media specifications, most importantly margin-boxes. Unfortunately the browser only supports few of the possibilities described in the specifications: if you want to add running headers, they need to be made by hand, there is no string-set nor position: running, paged.js is still necessary for most of the book design tools we need.

When we did our proposal to NLnet to modernize paged.js, here is the list of tasks we put on ourselves.

The full roadmap will be soon available on the website.

Use web components for reusable page elements

Paged.js is a big application that has small functions to do a lot of things in many places, and it may be hard for folks to start contributing back. One of the best examples of this is the template which is used when creating a page: it is a very long html string that contains everything: margin boxes, content-area, footnote area, etc.

So we decided to look at web components to make parts of the library easier to reuse.
The first element we made is the paged-page component that works as a custom print preview html element. It only takes a width and a height attribute and under the hood comes with all the required css to show a preview on screen, and it generates an @page block to instruct the browser on how the document should be printed. In Chrome you can now have multiple page sizes within the same PDF as each page has its own size properties.

It’s still undocumented because we’re exploring its API design: should the pages be separate components or slots to fill? Should we have bleed and cropmarks as custom component or are they set through an attribute?

But we wanted to share the progress with you, so here we are: you can check the code at the component on the github. We’re halfway through it, and we’ll eventually have a npm package.

It has become my main setup to build cssPrint preview, and I hope you’ll enjoy playing with it.

Use CSSOM for CSS parsing and manipulation.

As you might know paged.js relies on css-tree to convert the CSS as it is described in the standard, and as we write, into CSS supported by browsers. Browsers provide more and more API's for manipulating CSS, mosty notably the CSS Object Model, also known as CSS OM. CSS OM is like the DOM for CSS. It allows for quick CSS inspection and manipulation.

We started to explore what is possible with CSS OM by writing the CSS we'd use when making a book. Going through the CSS rules and adding, removing or changing them is so easy that it becomes fun to write CSS with javascript. (note that it’s not CSS in JS, but CSS with JS, we still want to write CSS, not adding another layer of abstraction. TLDR: it’s amazing for things too complex to write in CSS, like generative stuff, but absolutely useless to write your daily CSS).

One of the limitations of CSS OM is that you can only access the rendered stylesheet the browser will use to draw things on the page. CSS OM seems to provide access to the styleMap the browser has constructed based on the CSS it has parsed. The browser discards or ignores declarations, selectors and syntax it doesn't support, subsequently they are not accessible through CSS OM. So for example, there is no way to access comments written in the orignal stylesheet. If a CSS declaration has an unknown or unsupported property or value the declaration does not exist in the rendered stylesheet. The browser only manages the properties, values and selectors it knows. In the case of CSSPrint, we work with features that arent’t supported by browsers yet, exactly because paged.js wants to polyfill them. string-set? gone. target-counter? nada @footnote? lol. Until they get included in the list of features the browser support, we can’t have access to it.

I believe that manipulating CSS in browsers is better than any preprocessing. To do so, we need to make a conversion layer that will transform a stylesheet into something the browser will understand. Which is exactly what a polyfill is, this is exactly what paged.js is doing.

This layer will be a converter that will do a good amount of work:
- convert unknown values and properties into CSS custom properties (that we often too quickly call css variables);

replace unknown selectors into usable selectors before they get parsed by the browser.

With the possibility of having nested CSS and CSS custom properties, the amount of work is not that big, as we don’t have to rewrite everything from scratch.

A word about browsers
As you may have seen, we’re mostly talking about Chrom(e/ium) and derivatives, and that really hurt. Because we believe that paged.js should work in any browser. To do so, we’ll first make it work in Chrome, because that’s where we have fewer features to rebuild, since we can use a lot of what’s already inside. But right after that, we’re moving toward Firefox and Safari and whatever else may appear. It’s a question of energy and folkpower that we can’t really go against right now.
But mark those words, we refuse to be one of those Chromium only tool.

WPT Printing test

The amazing people at Weasyprint built a tool to run the Web Platform Test suite (WPT) on various tools aimed at making CSS Print. This is an amazing effort that will help all of us, so we want to take part of it. The same way we help writing new specifications we want to support the tooling that allows for better printing.

We looked at it with Guillaume from Weasyprint last week, and we’ll participate by using our knowledge to look how we can push it forward. We’ll most likely make some design work, to have improve the UX and UI, and we’ll make sure that the different version of paged.js work fine in there.

Pagedjs.org website updates

We’re almost done with this one. You may not have seen it, but we transformed the whole setup for the website by updating to the latest Eleventy, and we added a multilingual system. We can now write the same post in different languages, and, if you want to participate, you can make a translation of any post (it’s a simple markdown file) and make a Github issue for it. And boom, new language added.

We’ll be happy to see you contribute for any language. And if it’s not part of the website, you can contact us, we’ll make it happen :)

We still need to have a proper JSdoc export from paged.js repo, for developer’s documentation, ~~and we need to add RSS~~. (done, I was tired of not having RSS, so I decided to do it before publishing the article 😄 )

A quick look at the other tasks

Split out content fragmentation to its own library

The goal of this task is to get the chunker out of paged.js. The chunker is the part of the program that finds page breaks and handles the recreation of the HTML tree. Right now, it’s so intertwined with paged.js that it’s hard to reuse it without the paged.js page preview HTML structure. Our idea is that, when the chunker can chunk arbritary content into an arbitrary set of HTML elements, building tools with fragmented content in the browser becomes trivial. (For example chained blocks as we had back in the old days of CSS regions, but with a modern twist in how it would work with CSS).

And then, we will update paged.js to use that new library.

Update the fragmentation method to handle multiple break tokens

Following the previous point, we think it should be possible to have multiple content flows on the same page, with multiple break tokens this becomes much easier than the demo we made for the EPE project (https://github.com/pagedjs/pagedjs-experiments/blob/main/--paged-parallel-flows/parallel-flows.js).

Tagged PDF support

Yeah, that’s one of the hardest, but we want to provide some tagged pdf with paged.js. It’s a long term work, but we have that in mind on every step to make sure everything can work as expected.

So that’s what we did.

Starting in a couple of weeks, we’ll provide more frequent but smaller updates on what we’re doing and where we are, as we’re starting to look at options to support the effort on the long run.

Have a great couple of weeks

Parallel-flows within Paged.js

2025-07-26T00:00:00Z

While it is easy to imagine a multilingual book that would share its pages to accommodate content in two languages, it has always been difficult to imagine the web other than this long vertical flow, heir to the wheel. The content of a page starts at the top, and ends, when there is no more content to be placed on the page, well below what the screen shows, giving each illusion of infinity, what the attention economists have well integrated into their tools.

In reality, we have imagined some subterfuges to offer a semblance of parallel flow, from the layout through the `table' to the appearance of CSS or Flex grids, but it is always about the same downward movement, and even if the magic trick is invisible, because remarkably realized, it comes to mind when we wish to translate it on a paginated media.

The unfulfilled promise of CSS regions

When W3C editors work on the specifications for print, the web is not yet a world of web apps, of overpowered CSS and layout automation. We barely get out of the <table> layouts and we’re just discovering the wonderful world of floats. It is still The web of the document for which a page has a beginning (top) and an end (bottom). Suffice to say that when one thinks about printed matter, they do not look much further than to cut this flow into a sequence of pages until to form, for the most insane minds, a book.

Well, in fact, there have been attempts, one of which has been quite extensive: the CSS regions. This technique allowed the definition of spaces in which previously dissociated content streams could flow into the HTML code. And it was all but simple: the HTML was divided into two parts: on one hand the content, and on the other hand the container, associated with a complex CSS that defined the positioning of the boxes, and the shape of their contents. Yes that sentence was as complex as using css regions was. I will not go back here to the reasons why people in Chromium gave up the idea, because it would be too long and subject to so much controversy that we would lose the day (and a little mental health) arguing.

Just know that, within a few years, we had CSS regions in Chrome and we knew how to use them, and we made amazing things with it.

Moreover, Open Source Publishing, to which the CSS Print owes a great deal, has shown more than once the interest of such a practice. I think the best example comes from The Riddle.

And CSS Grid was.

If you look at the CSS presentation videos, the ones produced to push them into adoption, you always find the idea that it is about finding artifices of layouts that come from the book. And especially graphic experiments that come straight from the magazine press.

The CSS grid is the total step of the separation between the content and its form. If before these properties, the HTML was to give the order according to which items should be displayed on the page, this is not necessarily the case today, since the CSS offers authors the possibility to define, in addition to their form, the positioning and order of these contents.

The simplest way to look at a CSS grid is to see a touch-and-tip tray. To place each vessel, simply give its horizontal and vertical coordinates on a 2D grid. Therefore, the reading order is no longer descending, it is multiple, and depends on the organization of the page induced by the CSS.

However, the CSS grid has a fundamental limitation: no element can be separated into two blocks from this grid. The following image shows something impossible in CSS:

The print as a Trojan horse

The good thing about CSS print is that unlike the web, we are working on a page with limited dimensions, and that it is up to us to make the graphic and typographical decisions that allow the cutting of a long text into an infinity of smaller ones. Even if the W3C specifications show that questions have arisen and answers may have appeared, it is certain that the translation into print is an understatement of the evolution of the web.

First because print is only a limited use of our digital life and then because it would pose a thorny question: if we do it for a paginated media, why don't we do it for the web? If a printed CSS grid should allow the cutting of content on several cells, then why can't we afford it on the screen?

An interesting thing to do when a practice does not seem to exist on the web is to invest the field and start thinking about solutions, abstract enough to be reusable and clear enough to be explained, commented and analyzed.

The question of multiflux is difficult whatever the media, but it is the paginated media that seems to need the most answers, since unlike the screen, the paper is not infinite. Hence, here is a feedback on the multiflux in paged.js, organized around the project Screen Paper Edit, (EPE), led by l'Esad Grenoble / Valencia.

As part of the project, designers needed a solution to put texts in several languages and deal with them in the same way, avoiding placing one before the other. Perfect starting point to put the question of CSS regions on the table, now that CSS grids have become a central tool in web design habits.

pagedjs-multiple-flows.0.1d.js

If you want to take a look at the code first, it is here: parallel-flows. As i’m writing this, we’re on version 0.1d, working with paged.js 0.4.3 and 0.5b

paged.js parallel-flows is a Paged.js plugin that allows you to define so-called parallel streams (in the absence of a better name). The idea is to use CSS to define streams that will share a space, whether it is a page (several languages on the same page), or a double page (where each language has its own page).

It looks like this:

To do this, we use a custom CSS property we made, called --paged-parallel-flow. This property expects for value the name of a stream that will serve as an identifier. All elements that have the same value for this property will therefore be part of the same parallel flow.

Take this HTML for example:

<section id="alpha">content</section><section id="beta">content</section><section id="delta">content</section><section id="epsilon">content</section>

and this CSS:


#alpha {
--paged-parallel-flow: hand;
width: 30%;
}

#beta {
--paged-parallel-flow: hand;
width: 65%;
margin-left: car;
}

#epsilon {
--paged-parallel-flow: else;
width: 45%;

}

#delta {
--paged-parallel-flow: else;
width: 45%;
margin-left: car;
}

Note that each element already has investment properties: #alpha has a 30% width of its parent, #beta 65% and will be placed to the right, thanks to the use of margin-left: auto. The blocks defined here are therefore the locations of the containers as much as the contents.

#alpha and #beta must be treated at the same time and share one space, #epsilon and #delta share another.

The configuration of javascript

The javascript expects a specific configuration that informs about the type of flow and the choices of its implementation

The type of flow:

samepage: streams share the same pages
samespread: streams share the same double page

this.flowLocation = "samespread";

this.flowLocation = "samepage";

In the case of streams that would be configured to use samespread, you can automatically add a blank page if the streams are not of the same length.

this.flowSpreadAddWhite = true;

What's happening.

Paged.js finds the starting point of each flow and marks the first element as the starting point of the parallel flow.
Paged.js draws the two elements by following the CSS rules, to find the longest. This then becomes the main flow of this stream, and it is moved before the first element of the stream. Secondary streams are sent all at the end of the content to be processed in a second time.
Once the entire content has been paged, Paged.js finds each main stream and returns the secondary stream elements to the same pages (or adjacent pages in the case of a samespread), before deleting the pages that are now empty. Note: if it is a samespread, the pages are directly moved.

Bonus, an experiment.

Sometimes the main stream contains images. And it is not uncommon to want these images to exceed the width of text, without necessarily encroaching on the space needed for another stream. For this, we use --paged-parallel-impact: all. This experimental feature allows the main flow elements to impact the formatting of secondary flows. One case of use: an image dressed in the first stream, could dress the second. From a technical point of view, an invisible floating element is added at the beginning of this secondary flow, on the page or element A exists. This new item can be selected in CSS.

It is possible that the position of the added element is not correct, which is why it is possible to add the necessary changes to the css. To do this, you need to find the element identifier and add -overlap to your id.

For example:

#porco {
--paged-parallel impact: all;
}

To modify the manufactured overlap element, e.g. in the #alpha secion:

#alpha #porco-overlap {
width: 350px!important;
}

--paged-parallel impact works only if the image is in the main stream, since it is it that is set up before the others, and therefore cannot be modified thereafter. Reminder: the main stream is automatically detected, it is the most
long (taking into account objects and images). To do this, the script makes a first layout pass before sinking the content for good.

One last thing

Raphael, who’s testing the implementation is a smart mind, and like all developper as some very existencial issues, like: how to not have to redo the whole html to break the content is smallest bit to make sure they can be correctly set on the pages.

So he came up with the idea of parallel-sync. If you have two pieces of content you want to show next to each other, and they’re both one long string of HTML, you can use another custom property.

.en,.fr {
  --paged-parallel-flow: alpha;
}
h3{
--paged-parallel-sync: alpha; 
}

So if you have h3 in the different flows, they’ll wait for each other to start on the same page.

If you want to take a look at the code, it is here: parallel-flows. As i’m writing this, we’re on version 0.1d, working with paged.js 0.4.3 and 0.5b

Flux parallel avec Paged.js

2025-07-26T00:00:00Z

S’il est facile d’imaginer un livre multilingue qui partagerait ses pages pour y accueillir les contenus dans deux langues, il a toujours été difficile d’imaginer le web autrement que ce long flux vertical, héritier de la molette. Le contenu d’une page démarre en haut, et se termine, lorsqu’il n’y a plus de contenu à poser sur la page, bien en-desssous de ce que l’écran laisse entrevoir, donnant à chacune l’illusion de l’infini, ce que les économistes de l’attention ont bien intégré à leurs outils.

En réalité, nous avons bien imaginé des subterfuges pour proposer un semblant de flux parallèle, de la mise en page grâce aux table jusqu’à l’apparition des grilles CSS ou de Flex, mais il s’agit toujours de ce même mouvement descendant, et même si le tour de magie est invisible, parce que remarquablement réalisé, il saute aux yeux dès lors qu’on souhaite le traduire sur un média paginé.

La promesse non tenue des régions CSS

Quand les éditeurs du W3C travaillent sur les spécifications pour l’imprimé, le web n’est pas encore un monde de web apps, de CSS surpuissantes et d’automatisations de mise en page. On sort à peine des layouts de <table> et on découvre le monde merveilleux des floats (de l’habillage de texte, très conditionnel). C’est encore le web du document pour lequel une page a un début (en haut) et une fin (en bas). Autant dire que quand on pense l’imprimé, on ne cherche pas beaucoup plus loin que de découper ce flux en une suite de pages jusqu’à former, pour les esprits les plus fous, un livre.

Bon, en vrai, y a eu des tentatives, dont une assez poussée : les régions CSS. Cette technique permettait de définir des espaces dans lesquels faire couler des flux de contenu auparavant dissociés dans le code HTML. Et c’était tout sauf simple : l’HTML était divisé en deux : d’une part le contenu, et d’autre part le contenant, associé à un CSS complexe qui définissait les positionnements des boites, et la forme de leur contenu. Je ne reviendrai pas ici sur les raisons qui ont poussé les gens de Chromium à abandonner l’idée, par ce que ce serait trop long et sujet à tellement de controverses qu’on y perdrait la journée (et un peu de santé mentale). Sachez simplement que, l’espace de quelques années, nous avions des régions CSS dans Chrome et que nous avions su nous en servir.

Et d’ailleurs, Open Source Publishing, à qui le CSS Print doit énormément, a montré plus d’une fois l’intérêt d’une telle pratique. Je crois que le meilleur exemple vient de The Riddle.

Et CSS Grid fut.

Si on regarde les vidéos de présentation des grilles CSS, celles produites pour pousser à leur adoption, on retrouve toujours mentionnée l’idée qu’il s’agit de retrouver des artifices de mises en page qui viennent du livre. Et en particulier des expérimentations graphiques qui viennent tout droit de la presse magazine.

La grille CSS est l’étape totale de la séparation entre le contenu et sa forme. Si avant ces propriétés, le HTML se devait de donner l’ordre selon lequel devaient s’afficher des éléments sur la page, ce n’est plus forcément le cas aujourd’hui, puisque le CSS offre la possibilité aux auteurs de définir, en plus de leur forme, le positionnement et l’ordre de ces contenus.

La façon la plus simple de regarder une grille CSS, c’est de voir un plateau de touché-coulé. Pour y déposer chaque bateau, il suffit de donner ses coordonnées horizontales et verticales sur une grille en 2D. Dès lors, l’ordre de lecture n’est plus descendant, il est multiple, et dépend de l’organisation de la page induite par le CSS.

Pour autant, la grille CSS a une limitation fondamentale : aucun élément ne peux être séparé en deux blocs de cette grille. L’image suivante démontre quelque chose d’impossible en CSS :

Le print comme cheval de Troie

Le bon côté du CSS print, c’est que contrairement au web, on travaille sur une page dont les dimensions sont limitées, et qu’il nous appartient de prendre les décisions graphiques et typographiques qui autorisent la coupe d’un long texte en une infinité de plus petits. Même si les spécifications du W3C montrent que des questions se sont posées et que des réponses ont pu apparaître, il est certain que la traduction en imprimé est un impensé des évolutions du web.

D’abord parce que l’imprimé ne représente qu’un usage limité de notre vie numérique et ensuite par ce que cela viendrait poser une question épineuse : si on le fait pour un média paginé, pourquoi est-ce qu’on ne le ferait pas pour le web ? Si une grille CSS imprimée doit permettre la coupe d’un contenu sur plusieurs cellules, alors pourquoi est-ce qu’on ne peut pas se le permettre à l’écran ?

Une chose intéressante à faire lorsque qu’une pratique n’a pas l’air d’exister sur le web, c’est d’investir le champ et de commencer à réfléchir à des solutions, suffisamment abstraites pour être réutilisables et assez claires pour être expliquées, commentées et analysées.

La question du multiflux est difficile quelque soit le média, mais c’est le média paginé qui semble avoir le plus besoin de réponses, puisque contrairement à l’écran, le papier n’est pas infini. Dès lors, voici un retour d’expérience sur le multiflux dans paged.js, organisé autour du projet Écran Papier Éditer, (EPE), mené par l’Ésad Grenoble / Valence.

Dans le cadre du projet, les designers ont eu besoin d’une solution pour mettre en page des textes en plusieurs langues et les traiter avec les mêmes égards, en évitant d’en placer une avant l’autre. Parfait point de départ pour remettre la question des régions CSS sur la table, maintenant que les grilles CSS sont devenues un outil central dans les habitudes de web design.

pagedjs-parallel-flows

Si vous voulez d’abord jeter un coup d’œil au code, il se trouve ici : https://github.com/pagedjs/pagedjs-experiments/tree/main/--paged-parallel-flows.

`paged.js multi-flows est un plugin Paged.js qui permet de définir des flux dits parallèles (à défaut d’un meilleur nom). L’idée est d’utiliser le CSS pour définir des flux qui partageront un espace, que ce soit une page (plusieurs langues sur la même page), soit une double page (où chaque langue a sa propre page).

Ça ressemble à ça :

Pour ce faire, nous utilisons une propriété CSS inventé pour l’occasion, que nous appellerons --paged-parallel-flow. Cette propriété attend pour valeur le nom d’un flux qui servira d’identifiant. Tous les éléments qui possèdent la même valeur pour cette propriété feront donc partie du même flux parallèle.

Prenons par exemple ce HTML :

<section id="alpha">contenu</section>
<section id="beta">contenu</section>
<section id="delta">contenu</section>
<section id="epsilon">contenu</section>

et ce CSS :


#alpha {
  --paged-parallel-flow: main;
  width: 30%;
}

#beta {
  --paged-parallel-flow: main;
  width: 65%;
  margin-left: auto;
}

#epsilon {
  --paged-parallel-flow: else;
  width: 45%;

}

#delta {
  --paged-parallel-flow: else;
  width: 45%;
  margin-left: auto;
}

Notez que chaque élément possède déjà des propriétés de placement : #alpha a une largeur de 30% de son parent, #beta de 65% et sera placé à droite, grâce à l’utilisation de margin-left: auto. Les blocs définis ici sont donc les emplacements des contenants autant que les contenus.

#alpha et #beta devront être traités en même temps et partager un espace, #epsilon et #delta en partagent un autre.

La config du javascript

Le javascript attend une configuration spécifique qui informe sur le type de flux et sur les choix de sa mise en place

Le type de flux:

samepage : les flux partagent les mêmes pages
samespread : les flux partagent la même double page

this.flowLocation = "samespread";

this.flowLocation = "samepage";

Dans le cas de flux qui seraient configurés pour utiliser samespread, on peut automatiquement ajouter une page blanche si les flux ne sont pas de même longueur.

this.flowSpreadAddWhite = true;

Ce qui se passe.

Paged.js trouve le point de départ de chaque flux et en marque le premier élément comme le point de départ du flux parallèle.
Paged.js dessine les deux éléments en suivant les règles de CSS, pour trouver le plus long. Celui ci devient alors le flux principal de ce flux, et il est déplacé avant le premier élément du flux. Les flux secondaires sont envoyés tout à la fin du contenu pour être traités dans un second temps.
Une fois la totalité du contenu mis en page, Paged.js retrouve chaque flux principal et ramène les éléments des flux secondaires sur les mêmes pages (ou sur les pages adjacentes dans le cas d’un samespread), avant de supprimer les pages qui sont maintenant vides. Note : s’il s’agit d’un samespread, les pages sont directement déplacées.

Bonus, une expérimentation.

Il arrive que le flux principal contienne des images. Et il n’est pas rare de vouloir que ces images dépassent de la largeur de texte, sans forcément empiéter sur l’espace nécessaire à un autre flux. Pour cela, on utilise --paged-parallel-impact: all. Cette fonctionnalité expérimentale permet d’autoriser les éléments du flux principal à impacter la mise en forme des flux secondaires. Un cas d’usage : une image en habillage du premier flux, pourrait habiller le second. D’un point de vue technique, un élément invisible flottant est rajouté au début de ce flux secondaire, sur la page ou l’élément A existe. Ce nouvel élément peut être sélectionné en CSS.

Il est possible que le positionnement de l’élément rajouté ne soit pas correct, c’est pourquoi il est possible de rajouter dans le css les changements nécessaire. Pour cela, il faut retrouver l’identifiant de l’élément et rajouter -overlap dans son id.

Par exemple:

#porco {
    --paged-parallel-impact: all;
}

Pour modifier l’élément overlap fabriqué, par exemple dans la secion #alpha :

#alpha #porco-overlap {
   width: 350px !important;
}

--parallel impact ne marche qu’à condition que l’image soit dans le flux principal, puisque c’est lui qui est mis en page avant les autres, et qu’il ne peut donc pas être modifié par la suite. Rappel : le flux principal est automatiquement détecté, il s’agit du flux le plus
long (en prenant en compte les objets et images). Pour ce faire, le script fait une première passe de mise en page avant de couler le contenu pour de bon.

Une dernière chose

Raphael, qui teste l'implémentation est un esprit intelligent, et comme tous les développeurs comme certains problèmes très existentencial, comme: comment ne pas avoir à refaire le html entier pour casser le contenu est plus petit peu pour s'assurer qu'ils peuvent être correctement définis sur les pages.

Il a donc eu l'idée de synchroniser les titres, et nous sommes arrivés tous les deux à une solution ``--paged-parallel-sync`.

Si vous avez deux morceaux de contenu que vous voulez afficher à côté de l'autre, et qu'ils sont tous les deux dans deux éléments HTML distincs. Vous pouvez vous assurer que les titres démarrent tous sur la même page.

.en,.fr {
  --paged-parallel-flow: alpha;
}
 
h3 {
--paged-parallel-sync: alpha; 
}

Si vous voulez enfin jeter un coup d’œil au code, il se trouve ici : https://github.com/pagedjs/pagedjs-experiments/tree/main/--paged-parallel-flows.

A new chapter in Paged.js life

2025-05-17T00:00:00Z

I can still picture the room where Adam Hyde put Fred Chasen and myself around the table, looking at options for making PDF from HTML, and, while we couldn’t find a way that was satisfying enough, he looked at us, and said: “let’s just make it”.

And then we started. Very early in the process Julie Blanc joined, and within a couple of months we had a working proof of concept. In not so much more; a full fledge library. All of this was possible thanks to all the energy and resources Adam Hyde and Coko put into the project.

At that time the goal of paged.js was to show how CSSPrint could make single source publishing a reality. Most of our work was about helping folks who wanted to implement paged.js in their workflows, or build use cases around it and we were spending a lot of energy on workshops, book fairs, user support and demo projects. Plus, with the hook systems, people would extend the functionality of paged.js with their own scripts and manage to create amazing publications: from vote ballots, to complex (almost) automatic layouts. We were mostly helping folks implementing complex algorithms for print or even implementing some of it ourselves.

At some point, we were doing more work to help users with paged.js than we spent updating paged.js' core code, features or documentation nor kept the community in the loop of what’s happening.

So let’s change that, welcome to paged.js 2.0

Didn’t you skip a number? Where is 1.0?

The idea we had with paged.js was that, at some point, the browser would do the work of supporting paged media specifications and folks could get rid of paged.js all together, simply use the browser for all their pdf needs, and we could stop working on it. The goal of the project was to render itself ultimately redundant. But what we discovered on the path is that paged.js is more than a polyfill for future features, it’s also a gateway to css print because of the preview you get on the screen.

In short, when you use paged.js, the library will take your html and css, find all the properties used for print (@page, margin-boxes, target-counter, etc.), and replace them with html and css to preview, on screen, what will appear on paper (or in the PDF). This allows you to inspect your pages, look at the css, test changes in context and run paged.js again. And print from the browser, which doesn’t use the css for print, but the converted css you have on the screen.

And then, Chromium team did what we wanted them to do before paged.js: they started to implement print features, starting with the margin-boxes. Hopefully, it will push other engines to do the same. But, in the meantime, things get tricky for paged.js.

Supporting chromium updates would mean transforming paged.js in such a way that firefox or other browsers would be left behind, which goes against our goals. Yes, we did repeat that chromium was better because it allows for custom page sizes and manage widows and orphans better, but Firefox, or Safari, or any other browser would still be a valid option.

Therefore paged.js needs to change to support more engines and more contexts of use. As this is a breaking change we’ll jump to paged.js 2.0 very quickly.

So long paged.js, hello paged.js neue

First, paged.js members are part of a NGIzero supported project, Pushing forward for CSS Print, for which we’re joining force with the lovely Lucie and Guillaume of Weasyprint (a python based engine to make PDF out of HTML and CSS) to push #CSSprint forward. We’ll write down new specifications to print with CSS and implement them in weasyprint and paged.js, in order to push the conversation forward with the W3C folks. (You can check our Notes on notes to see some examples of what we could do).

Second, Paged.js has also been accepted for a NGIzero grant to support the important structural update of paged.js and its dependencies. This plan of update includes a lot of breaking changes: removing CSSTree to replace it with cssOM, use web-components for pages, and document, transform the chunker into its own library, change the algorythm that find breaktoken, allows for multiple break tokens, etc. We’ll cover more of that in the future updates on the blog, as soon as we have a proper calendar to share. The grant is only available for a year so that’s already a nice information.

Meet the team

First, Gijs de Heij is joining the team as a core maintainer. While Fred is working a fulltime position at Mozilla, we decided to redraw how the team works around paged.js. Instead of putting everything of Fred’s shoulders, we’re moving toward a team of core developers, as Gijs and myself will be more involved into paged.js development by contributing codes, features and managing user support.

Gijs is an amazing designer / developer and a member of the collective Open Source Publishing, he’s been a long time user of paged.js and experienced first hand what works, what doesn’t, and what needs a work around.

As Fred’s time is reduced, his work on paged.js will be less visible, and though Julie officially stopped working on paged.js when she started working on her thesis she’s still around paged.js and part of the Weasyprint × Paged.js project. By now she's Julie Blanc, PhD, afters she defended her thesis “Composer avec les technologies du web ” (Composing with web technologies. Collective instrumental genesis for the development of a community of practice of graphic designers), it observes how paged.js was used by graphic designers to share knowledge and build communities.

Coko has been supporting paged.js for all of us for a long time, and we wouldn’t be where we are now if it wasn’t for Adam Hyde’s time, energy, trust and generosity. I don’t think I’ll ever be able to thank him enough for all the support he gave to each one of us. And even though Coko is not financially supporting paged.js anymore, Adam is still around to help, and we wouldn’t like it any other way.

On paged.js future

This post is already too long. So, to not take too much of your time, some final practical updates:

Paged.js now has a mastodon account on fosstodon: https://fosstodon.org/@pagedjs, we won’t be using twitter anymore.
Paged.js code (and submited issues) are now on github, as well as the sources for this website, and we’re slowly bringing back some of the plugins and snippets we developed here and there. (https://github.com/pagedjs/)
You can reach us by email: [email protected]">[email protected]
Paged.js now has a Matrix channel. Come to chat and discuss the futur with us: https://matrix.to/#/#pagedjs:matrix.org
The website is now fully internationalized. Thanks for the amazing amazing (not a typo, i wrote it twice) Eleventy. You can now join the translation effort if you feel like it :D.

There are a bunch of other things to share in the coming weeks, from pagedjs structural changes to documentation update/rewriting (for devs & users), and other things we want to bring back (plugins, templates, etc.)

With the hope that you’ll want to take part in Paged.js future, as you may have done before.

See yall very soon.

Le prochain chapitre de Paged.js

2025-05-17T00:00:00Z

Je me souviens précisément de la pièce où, accompagné d’Adam Hyde et de Fred Chasen, nous regardions les possibilités existantesp pour transformer du HTML en PDF, et alors qu’on ne trouvait rien de probant, Adam s’est arrêté, nous a regardé et à dit : Let’s just make it.

Et nous voilà partis. Julie Blanc nous a rejoint très vite, et au bout de quelques mois nous avions un preuve de concept fonctionnelles, et en moins d’un an, une bibliothèque javascript capable de produire des PDF. Rien de tout ça n’aurait pu être possible si Adam et Coko n’avaient pas autant investi de temps et de ressources dans le projet.

Les années qui ont suivi ont surtout été le moment de mettre le CSS Print sur le devant de la scène, comme pierre angulaire du single source publishing. La majorité de notre travail consistait à accompagner les utilisateurs de paged.js, que ce soit pour de accompagner des implémentations & des workflows, former des designers et des éditeurs aux concepts de web to print, participer à des salons du livres et évenements professionnels, et, lorsqu’il restait un peu de temps, accompagner des projets de livres numériques multi-formats.

Avec Paged.js et son système de hooks, on a vu apparaître une quantité importante de documents produits avec Paged.js, qu’il s’agisse de rapports scientifiques, de bulletins de vote US, d’articles scientifique à la mise en page quasi automatique, et c’est avec une grande fierté que nous avons pu participer à quelques-uns de ces chantiers.

Mais ce travail a un coût et si on a pu accompagner des projets, nous n’avons pas été des plus efficace pour tenir au courant la communauté des changements, mises à jour et autres expérimentations.

Il est temps de changer ça et de passer à paged.js 2.0

2.0 ? Mais où est passé la 1.0 ?

Une idée que nous avons gardé en tête depuis le début de paged.js était que, tôt ou tard, les navigateurs allaient implémenter les fonctionnalités que nous utilisons si bien qu’à la fin, nous pourrions nous séparer de paged.js pour de bon. Mais ce que nous avons réalisé en chemin, c’est que le polyfill n’est qu’un usage restreint de Paged.js qui passe à côté de sa fonctionnalité principale: la prévisualisation à l’écran de ce que donnera le document imprimé permet d’imaginer les usages futurs du CSS Print.

Pour faire simple, paged.js va lire votre HTML et votre CSS, va trouver les fonctionnalités utilisées pour le print (@page, .footnote, etc.), et va les convertir en HTML et CSS que le navigateur va pouvoir afficher à l’écran, rendant possible l’usage de l’inspecteur, meilleur ami de tout bon développeur web, pour imprimer la page en utilisant la fonction save as PDF du module d’impression. Dès lors, le navigateur n’imprime plus seulement la feuille de style pour le print, mais aussi ce que l’utilisateur voit dans sa fenêtre. Plus vraiment un polyfill mais un nouvel outil.

La deuxième chose importante date de fin 2024, quand l’équipe derrière Chrome décide d’augmenter la voilure sur l’implémentation des features de print, en commençant avec les margin-boxes. Bonne nouvelle, CSSPrint avance, autre bonne nouvelle, mais plus technique, paged.js doit évoluer.

Si l’on transforme paged.js pour suivre les mises à jour de chromium, alors paged.js devra tellement changer que les autres navigateurs risqueraient d’être abandonné. Même si chromium a une petite longueur d’avance sur quelque fonctionnalité que nous utilisons déjà (en particulier les veuves et les orphelines, ou la possibilité d’imprimer d’autres formats que les standards), nous continuons de penser que chaque navigateur est une option solide pour imprimer.

Alors il faut changer la façon dont paged.js fonctionne pour être plus stable avec plus de moteur de rendu, et comme il va y avoir un nombre de changement important, passer à paged.js 2.0 nous semble être la meilleure solution.

Paged.js neue

D’abord, les bonnes nouvelles.

NLNet, par le biais de NGI 0 accompagne cette transformation de paged.js sur plusieurs projets.

Le premier, Pushing forward for CSS Print est une mission partagée entre l’équipe de WeasyPrint (les fantastiques Lucie et Guillaume) et Julie Blanc et Julien Taquet (moi-même), contributeurs de Paged.js. Ce projet finance l’écriture de spécifications pour le CSS Print pour aller plus loin que ce que nous pouvons faire aujourd’hui. La pemière de ces spécifications est la continuité du travail que nous avons commencé sur les notes. La spécification est en cours de discussion et va intégrer les conversations avec les W3C (vous pouvez la lire et la commenter ici : https://css-print-lab.github.io/specs/notes-in-css-print/).

NlNet finance aussi un second projet, autour de la mise à jour de paged.js vers le 2.0. Parmi les changements qui arrivent on trouve le remplacement de cssTree par CSSOM, l’utilisation de web-components pour la partie dev, sortir le chunker de paged.js pour en faire une dépendance et permettre l’utilisations de plusiers breakTokens. Nous reviendrons là-dessus plus en détail dans les semaines qui arrivent avec un calendrier plus clair. Le financement ne peux durer qu’un an, ça donne une petite idée de la vitesse avec laquelle nous devons avancer.

La nouvelle équipe.

Depuis que Fred a intégré Mozilla à temps plein, le temps qu’il peut fournir à paged.js s’est sensiblement réduit. Nous avons décidé de lui alléger un peu les épaules en transformant un peu l’équipe autour de paged.js

Le premier changement est l’arrivée de Gijs de Heij dans la core team. Gijs est un designer/developer, membre du collectif Open Source Publishing et manipule paged.js depuis suffisament longtemps pour savoir ce qui marche et ce qui va poser problème :)

Le second changement est mon implication dans le code de paged.js. Jusqu’à présent, il s’agissait d’accompagner Fred et de tester les changements pour en rendre compte à la communauté ou proposer des plugins. Je serai beaucoup plus partie prenante dans la mise à jour du code, l’implémentation de features et l’écriture de spécifications, en plus de m’assurer que tout le monde soit ravi, que les frustrations soient réduites et que les contributeurs se sentent à l’aise.

Sur le reste de l’équipe, Fred est toujours là, mais son temps sera forcément moindre, et si Julie ne fait plus partie officiellement de l’équipe depuis qu’elle a commencé à écrire sa thèse (dont le sujet ne peux être plus dans le mille: “Composer avec les technologies du web ” , et qu’elle a soutenu avec la plus jolie des réussites), elle n’est jamais vraiment loin de l’équipe, ni des questions qui nous concernent.

Coko a été un super espace dans lequel dévlopper paged.js et nous ne serions pas là où on en est sans le temps, l’énergie, la confiance et la générosité d’Adam Hyde, et si Coko ne participe plus au financement de paged.js, Adam n’est jamais loin pour nous aider.

À propos du futur de paged.js

Ce poste de blog est déjà trop long, alors je ne vais pas vous prendre plus de temps, mais je dois dire en quelques mots:

Paged.js a un compte mastodon :)
Le code de paged.js et son site internet sont maintenant hébergés sur Github (https://github.com/pagedjs/), et nous sommes en train de rapatrier ce qui traîne sur des repos ici et là sur les différents serveurs git que nous avons pu utiliser.
Nous sommes joignables par mail [email protected]">[email protected]
Pagedjs a maintenant un channel Matrix pour discuter du futur du projet https://matrix.to/#/#pagedjs:matrix.org
Le site de paged.js a subi la mise à jour du fantasique Eleventy et permet donc l’internationalisation de tous ses contenus. Sérieusement je crois pas qu’il y ait meilleur générateur de site statique.

Nous avons pas mal de choses dans les cartons, en particulier sur la partie réécriture de la documentation (de développement ET pour les utilisateurs) avec l’espoir de trouver la bonne solution pour que, si vous souhaitiez participer à son élaboration, nous puissions vous accueuillir du mieux possible.

On se retrouve très vite.

julientaq

So long @media screen!

2022-11-11T00:00:00Z

Hey folks.

Yesterday night, our amazing Fred Chasen jumped the gun and pushed the 0.4.0 to
npm, making it the base version for any of you who use npm without version
control, or simply call from the unpkg cdn (or any other cdn).

That means that if you opened your previous file without knowing what would
happen, you must have had a bit of a scary moment. Don’t worry too much,
the breaking changes were not about how paged.js works, but more on how Paged.js
previews things on screen.

I want to go back to have a preview on screen!

Yep! Absolutely, it’s (one of) the great features of Paged.js, and we have a
couple of solutions for you.

We explained it last time (you can read the post
here, but we
moved forward to follow the standards for the media queries. So, from now on,
pagedjs will ignore any rule that should not apply to a media screen. @media screen being the most useful example.

The most standard change, for all of you, is the preview on screen: if you want
to use the interface.css we’re making, you can simply update and use the
https://gitlab.coko.foundation/pagedjs/interface-polyfill/blob/master/interface.css
for version 0.4.

Note that if you have some css for the screen that you want to force pass to the
browser (for example to allow an UI around paged.js) then you can use the
pagedjs-ignore property in the html <link rel="stylesheet" type="text/css" href="screen.css" pagedjs-ignore> or in the css : @media screen, pagedjs-ignore { .pagedjs_pages {margin-top: 20em} }

Again, the previous post will tell you all about it. The good thing is that the
styles for the screen and the paper will stop hurting each other.

Enough with breaking changes, we want features!

And features you’ll get! Here are the release notes from the merge requests,
explained.

You can now have multiple nested named pages:

Until now, you could only have one level of named page. This will fix that by
allowing nested named pages. For example, if this is your html

<div class="content">
	<div class="preamble">
		<p>This is a preamble.</p>
	</div>
</div>

and this is your css

.content {
  page: contentpage;
}

.preamble {
  page: preamble;
}

then the Preamble will be on its own page!

We have an index for all the tests we have in pagedjs (we call’em specs)

An image is better than a long talk right? So this is what we support.

Ok, so no, the image is not always better, especially as it’s an inaccessible
way to show information. So if you want to see what we support, you may want to
go there too: https://pagedjs.org/documentation/cheatsheet/ It’s needs a bit of
an update so feel free to open an issue and help us writing down the most
accurate feature list we can have. Please be in touch at
https://mattermost.coko.foundation

Tables improvement.

Paged.js used to cut table at the first block of text overlapped the page height,
and this caused a column shifting beteen pages. While this was very fun to look
at, it was a real pain for people who worked with tables. So this is now a bit
better.

Fred also fixed an issue where multiline content would break tables after a
page break.

Tables are still problematic when they get long and overly complex but
we’ll get there eventually.

There is a new hook in town.

Say hello to finalizePage. This hook runs just before the page is considered
rendered, after page layout is completed. When paged.js is done with the
afterPageLayout if run finalizePage. This allow us to manage any changes
that occurred in layout or when generated content was added.

Looping is gone (but being a loop, it may be back)

A looping in Paged.js world is when a code tries to do something, can’t do it and
tries again. and again. and again. The best example we have of that is when you
try to add an image on the page and there is not enough room for it. Paged.js
will create a new page, try to put the image on the page, and again, and
again, and starting to go into that infinite loop that never end.

From now on, Paged.js 0.4 will gracefully stop when that happens.

One but not least

You can now reuse attributes from your element as information for your running
headers:

<p id="funny-p" data-fun="total">this is so nice</p>

With that css :


#funny-p {
  string-set: alphabet attr(data-fun);
  }

will allows you to reuse the attribute as part of your generated content:

@page {
  @bottom-center {
    content: string(alphabet)
  }
}

this will put in the margin bottom of the page the word total, since it’s the
value of the data-fun attribute

Better, you can now have multiple string-set, if they are separated with
commas:


h1 {
  string-set: titletext content(text) , datafun attr(data-fun)
}

That’s all folks!

We’ll be back soon with some nice example of Paged.js!

Take care

Paged Break, the long overdue update

2022-07-10T00:00:00Z

It’s been a while, hasn’t it?

That’s how it feels for us. Not that we weren’t around working, quite the opposite to be honest, but it wasn’t very visible outside of the Coko chat (You should join if you’re interested in the future of Paged.js as we try more and more to discuss things in the open out there). We also try to offer some news on Twitter, so make sure to follow if you want some last-minute news, or if you want to ask some questions a little bit.

Still, it feels nice to fill those pages after a year of being silent so let’s try to catch up to what happened as we’ve been a tiny bit busy.

Before we get into that, we had to move our repo from the GitLab we had at pagedmedia.org to https://gitlab.coko.foundation. Because Paged.js is maintained by the Coko Foundation and also because we got hit quite hard by a crazy spam that literally killed the server again and again. We’re now in a much better space as the nice folks of cloud68.co are now in charge of making our life easier, and they’re quite good at it. We managed to save the important repos and all the comments and conversations, thanks to Boris.

Ok, back to Paged.js

Between June last year and this month of July, we’ve been through a lot of small changes, going from 0.2.0 to 0.4.1 beta (we do have beta now!)

Before explaining the changes, a small shout-out to our friendly users who came up with fixes. So thanks to Anthony Libotte, Guillaume Grossetie, Thomas Parisot, Angela Liu to name a few (along with the amazing work from Fred Chasen).

We won’t spend too much time on the small fixes as they’re mostly updates to preexising features, including, better support for footnotes, a new div to be able to center things vertically, and those kinds of things. The release note for each merge request tells more than what I could write here.

But then, here are the breaking changes.

Goodbye web2print, hello web+print

A reminder: Paged.js is a polyfill, a Javascript library that does what the browser should be doing by itself. That means that what you do with Paged.js today needs to be what you will be able to do in Chromium, Firefox, Edge, Vivaldi, etc in future -- one day, the browsers will have implemented the print feature and when that happens, we won’t need Paged.js anymore

To be a working polyfill, Paged.js needs to work exactly like a browser.

In a browser, when we set @media queries, we can define styles for a specific environment. We know that well because that’s how responsive design works: you define what happens when the usable surface is smaller than 800px @media (max-width: 800px) or when night mode is wanted @media (prefers-color-scheme: dark) or simply when you want to print something with @media print.

If you don’t set any query, then your CSS will be used in all situations.

So a simple example: we have some <h1> and we want them to have a font-size of 2em in all situations, but we want them red on screen, black on paper. This is how it will be set.

/* shared for all the context */  
h1 {  
  font-size: 2em;  
}  
  
/* only for screen */  
@media screen {  
  h1 {  
    color: red;  
  }  
}  
  
/* only for print */  
@media print {  
  h1 {  
    color: black;  
  }  
}

Until now, you needed to have a custom stylesheet for pagedjs to handle what happens in print and on screen. If there were some styles defined for the screen in the stylesheet, they were also rendered in the preview.

In the example above, it takes the latest value defined in the CSS cascade: the h1 would be black on screen and on paper.

That’s the result of rendering the print preview on screen, creating the perfect paradox where eveything is used. Paged.js tricked the browser to show you the styles from the CSS for print, in a screen context, because we preview those pages, on a screen.

Now, with this new feature, Paged.js will hide what’s for the screen and show what will be printed. Starting with version 0.4.1, Paged.js will stop parsing any css that is inside a @media screen media query. In other words:

/* This will be completely remove from the page when you run Paged.js */  
@media screen {  
  p {  
    color: red;  
  }  
}  
  
/* this will be used by Paged.js */  
@media print {  
  p {  
    color: purple;  
  }  
}  
  
/* this will be used by Paged.js as it an equivalent of @media all */  
p {  
  color: purple;  
}

But as we’re moving toward html AND print, we needed to change Paged.js a bit. In the previous post from Julie, she showed how we could create a designer interface around the paged.js preview feature: show baseline, show margin boxes, etc. To make that work, she added content as a hook: when paged.js was done, it would show the toolbar, making it hard to work with (and absolutely not standard). This update will change that.

So now, if you want to use the polyfill and have have elements just for the screen preview, you can use one of the following ways:

Put all the interface rules in a seperate stylesheet that has a media="screen" attribute, which won’t be parsed by the polyfill and only applied to screen media:

<link rel="stylesheet" type="text/css" href="screen.css" media="screen">

Or add a media="screen" attribute to any style tag to apply those rules to screen media and be ignored by Pagedjs:

<style media="screen">  
  p {  
    color: red;  
  }  
</style>

Additionally, you can tell Paged.js to ignore any CSS you don’t want parsed with the pagedjs-ignore attribute:

<style pagedjs-ignore>add some inline styles</style>  
<link rel="stylesheet" type="text/css" href="screen.css" pagedjs-ignore>

This way, pagedjs will pass the stylesheet as it is, and will not update the styles. One important note: if you are ignoring screen styles, you want to make sure that you’re writing in a media screen to avoid the styles being mixed up on export.

Finally, in a parsed CSS file, adding pagedjs-ignore will skip a media block, passing it as it is to the browser. This is pretty useful to define how the page will look in the browser:

@media screen, pagedjs-ignore {  
  .pagedjs_pages {margin-top: 20em}  
}  
  
@media pagedjs-ignore {  
  // block to pass  
}

One fair warning, this is a bit outside of the standard, it’s a usable workaround that we’ll support by default, but pagedjs-ignore has no intention of being a standard in the future. But it’s a way for you to build the tool you need around real media queries support.

You can test it already if you’re using Paged.js 0.4.0-beta.1, using the interface.css polyfill: https://gitlab.coko.foundation/pagedjs/interface-polyfill

We’ll let that work as a beta for a month before making a proper release.

The simplest way to use it is to get the file from unpkg cdn: [email protected]/dist/">https://unpkg.com/browse/[email protected]/dist/ and see how things work for you.

If you find any issues, or anything, feel free to open an issue on our GitLab, or contact us on the Mattermost (again, the best way to get in touch with us.)

We’ll be back soon with some other updates, as Paged.js CLI also got pimped up! if you want to test the CLI with the aforementioned changes to Paged.js, you’ll find the files here: [email protected]/">https://unpkg.com/browse/[email protected]/

One last thing, 27-28 October 2022 in San Francisco will see the first Page Break Conf which has been organized by some great folks of our community. We’ll be back to talk a bit more about it soonish, so don’t forget to save the date!

Have a nice printing!

A collection of starter kits for Paged.js

2022-04-15T00:00:00Z

We’ve done a lot of work to bring new users to paged.js and as i’m on my way to a new workshop with graphic design students, I thought that it would be a good time to share a little bit more about the different starter kits I've build around Paged.js since a few years to help anyone to get started.
And since not everyone has the same needs, it will be four stater kits instead of one.

Depending on your needs, you can start from these ready-made folders that contain Paged.js, some CSS reset code, a bit of interfaces and sometimes JavaScript features to help your work. Choose the right one !

The spread book template: the lightest starter-kit

This is the simplest template, which uses the polyfill in an HTML page. The folder is already structured for you:

An HTML file where to add the structured content of your book, the file contains the links to all other files and elements;
A CSS file that help you to see your book in spread and where you can add the visualization of a baseline (Be careful, this visualization in spread and the baseline is only for the screen. When rendering the PDF, it will be page by page again.)
A CSS reset file to normalize the style of some elements;
The folder for your assets: a fonts, an images and a scripts folder where you can add your custom scripts with a pre-coded handler;
And, of course, the latest version of Paged.js.

This starter-kit exist in two version: the polyfill version and the esm module version. The difference is the way Paged.js is called on the web page. The esm version is more flexible if you want to add your custom scripts to Paged.js or integrate it with other tools.

The polyfill version contains in addition a little helpful script developed by the great Nicolas Taffin, the reload-in-place script: “On reload, it will make the web browser scroll to the place it was before reload.”

You can easy add it this template in an existing site, in a print folder for example. This will allow you to access a special page to print a part of your site. All the HTML content of your site must however be rewritten in this HTML page.

The advanced interface template: to facilitate your design process

This advanced starter-kit contains a little interface and some features to help you during your design process. It's a template that I developed during workshops for graphic design students not used to code but which can also be used for the production of books on a daily basis. All the element of the previous “spread book template“ are also in this start-kit. I also added different features that can be used with buttons always present on the web page:

display of the baseline with modification of its values,
display of margin boxes,
“visualization” mode where the cut lines are hidden,
print button
And number of generated pages displayed.

The “print-a-webpage” template: a responsive web page that can be printed

The last start-kit I propose is the “print-a-webpage” template. It offers a double view of a web page: the classic web page for the responsive screen display and a paginated display for printing. Both displays are made from the same HTML content but the CSS for each version are separated. Buttons on the side of the web page allow you to switch from one version to the other or to print.

In the printed version, all the element of the previous “spread book template“ are also in this start-kit, except the reload-in-place script.

Don't forget your local server

Before your start, just a reminder: you need to use a local server to work on your project. Paged.js needs it to make links from one file to another and in particular to read yourCSS files. Today, all the most used text editors have extensions to launch a local server (Visual Studio, Atom, Sublime Text, Atom).

If you haven't done it yet, you just have to install one of these extensions and launch the local server from your project. Please note that the entire folder of your project must be open in your editor for the local server to work properly.

Most of the errors and difficulties come from the fact that the local server is not turned on, so I advise you to be particularly vigilant on this point.

You are now ready to get started with Paged.js! We would be very happy to see your productions, so jump on the Coko Mattermost to say hello (~pagedjs channel) or contact us on twitter.

Uke and inks

2021-06-18T00:00:00Z

Editoria, the Book Production Center

Editoria is a platform to collaboratively produce books, offering spaces for writers, editors, designers, etc. at the same time the content is being added.

We've been talking Editoria quite a lot in these pages. Firstly because Paged.js was implemented in Editoria before any other tool, after years of trying out other tools to make books out of HTML.

Editoria has been used for quite a while by Book Sprints and other friendly folks. It's a pretty amazing tool for creating books collaboratively by a team. But one of the limitations from the designer's perspective was that we were stuck with what CSS allowed us to do. It took quite a while to figure out the best option to have custom javascript hooks without compromising the security of the whole platform.

Well, that solution exists now:)

To show what you can do with Editoria nowadays, I have produced a small demo book, with some paged.js hooks that I explain in this post.

Before jumping into hooks, let's briefly explain how paged.js does what it does.

Paged.js: hooks and order

Fred Chasen made paged.js around a clever idea: instead of defining the order of events that paged.js needed, he defined the moments where you would need to do something on the content, and set those as hooks to which you can bind your scripts.

All the modules use those entry points to do different things at different moments.

when it's about to parse the HTML, CSS and JS.
when all the content has been parsed.
when you create a new page
when you put one element on the page
when the page is filled and there is no more space left on the page
when you define the exact location your content is split
when you finish the layout of the page (go back to 3)
when you zend the signal that all pages are generated if there is no
content left.

You can see all the existing hooks on this page if you want to go deeper.

For example, let's look at how a break-before: left is defined.

Before the HTML, CSS and JS of the document is parsed.

check if any element has a break-before property and if it’s value is left, add a data-break-before: left attribute to it.

when you lay out one element on the page

if that element has a data-break-before: left attribute, stop adding elements to that page and jump to 6. Then, if it’s a right page create an blank page and resume adding content on the following page, else (if it’s a left page), resume adding the content.

As you can see, the algorithm is crystal clear, and when the browser handles features, we'll be able to remove those that become useless over time.

Let's start strumming our ~~ukulele~~ keyboard and make some code. :)

Where the humuhumunukunukuapuaa goes swimming by

So let's jump in, script by script and see what happens and how things work.

Here is the link to the pdf and to the repo if you want to have a proper look at all those files :D).

We’re setting up a place to display the open source templates we’re making, so stay tuned to know more about it.

Changes in the DOM

Wax, the word processor that fuels Editoria, treats the content as a
flat flow of elements. You can define the type of block from a list of
styles (including custom styles for both inline and block level
elements). The output of that is a nicely set HTML with paragraph with
different classes, header, em, and all the other sweets the HTML has to
offer.

If all is so great, why would we change the DOM?

For multiple reasons:

You may want to bring elements together (for example, when you have
two figures that belong together and for which you want to have a
specific layout), or when you want to nest stuff together, something
that your editor may not offer.
To redo something the browsers used to offer (nope, not the CSS
regions, not this time :D) such as the unknown display:
run-in which allowed us to
push an element to the next as an inline block. This trick has been
used a lot in the world of print, and it was available for the
screen a long time ago. But it didn't survive the test of time.
You may want to create, let's say, an index. To do so, you need to
create links between the words and their counterparts in the index.
In this book, I used a custom inline class to list everything the
musician talked about in the first chapter to build the list in the
end.

My first script, the contentUkulele.js is happening on the beforeParsed
hook (before any content data has been processed by paged.js). It's
removing empty elements, add id to elements that don't have ids yet,
recreate the display: run-in property. Nothing really fancy here, but it
let me create the DOM I want s /I can start designing the book itself.

Page-float? Are you going to talk about page-float?

Yes.

And no.

Not in the way you're expecting it.

If you want to know what a page-float is, and what it can add to our
layout, you should have a look at the
[demo]{.ul} Julie Blanc
made. Be aware that this is not inside Paged.js (yet) but a good demo on
how things should work when we'll be able to follow the specs from the
W3C.

Truth is, page-floats are a pretty complex thing (check Julie's article
[about page floats]{.ul}). There
are a lot of different ways to implement page-floats, and they all come
with pros and cons. Until we find the universal way of making page-float
a thing, we can still find workarounds and ways of making it work. So
let's see how I did it for the ukulele book.

The custom property with its custom values

This image-handling.js script has only one role: find the element that
has that property, and depending on its value, add a specific class to
that element so we can target it when it's being rendered on the page.
To do so, I created a CSS custom property that can have different values
to define where the element should float.

--page-float: same-top, same-bottom, next-top, next-bottom, same-column-top,
  same-column-bottom, next-column-top, next-column-bottom, full-page;

Some of those values/classes are not used, but are there for the day we
need them.

Layout time!

Then we have a float-top.js, floatNextBis.js or fullPage.js that handles
the moving of elements on the page when they are rendered.

Let's check the easiest of those scripts: fullPage.js:

First, we define the name of the class for the image full page.

const classElemFullPage = "imgFullPage";

Then, we create our hooks like this:

class fullPage extends Paged.Handler {
  constructor(chunker, polisher, caller) {
    super(chunker, polisher, caller);
    this.floatFullPage;
  }
}

Hooks are sharing the same constructor. That means that if you want to
set a variable and use it in different hooks, you need to set it in the
constructor. In this script, I'm creating a this. floatFullPage that we're going to use to find the elements that have the --page-float: full-page; custom property.

onDeclaration(declaration, dItem, dList, rule) {
  if (declaration.property == "--page-float") {
    if (declaration.value.value.includes("full-page")) {
      let sel = csstree.generate(rule.ruleNode.prelude);
      sel = sel.replace('[data-id="', "#");
      sel = sel.replace('"]', "");
      this.floatFullPage = sel.split(",");
    }
  }

onDeclaration is a hook that happens every time a declaration is found.

When that happens, we check if the declaration property is --page-float and if the value is full-page. If that's the case, we get the value from of the selector (sel) using csstree. And we push that value to the this.floatFullPage array.

Then, when the content is parsed, we use the selectors from this.floatFullPage to add the fullpage class

afterParsed(content) {
  if (this.floatFullPage) {
    this.floatFullPage.forEach((elNBlist) => {
      content.querySelectorAll(elNBlist).forEach((el) => {
        el.classList.add("imgFullPage");
      });
    });
  }

Then, the magic happens: every time a page is done, we run the following script:

afterPageLayout(page) {
  if (page.querySelector(".imgFullPage")) {
    console.log(page);
    page.classList.add("fullPage");
    page.querySelector(".imgFullPage").style.display = "none";
    page.style.background = `url(${page.querySelector(".imgFullPage").src})`;
    page.style.backgroundRepeat = `no-repeat`;
    page.style.backgroundSize = `cover`;
    page
      .querySelectorAll(".pagedjs_margin-content")
      .forEach((marginContent) => marginContent.remove());
  }
}

When a page has a child with the class full-page, it will hide the image, and use the src attribute of the image and use it as the background for the page. We also put some css styles in there to make sure the background cover the whole page. And one last thing: we remove all the elements in the margin boxes on that page.

The page breaks that arrive before and after are set in the css for the same element.

And the last thing, we register the hook.

Paged.registerHandlers(fullPage);

We use the exact same idea for the image to top / bottom, but we're moving them as soon as they're on the page, and we use the amazing shape-outside property. We'll cover that deeper in the next installment of this series.

Until then, keep practising music and book design.

The code is accessible here

Have fun!

Paged.js 0.2.0 Release notes

2021-06-01T00:00:00Z

Hey yall! We have footnotes!

One day, i said on twitter that we were starting our work on the footnotes. This was the most retweeted and shared post in all the history of Paged.js. This is the most awaited feature that we’re really proud to bring into the game.

We’ve always been happy to help making hooks for footnotes, but they were mostly hacks, and would come with their share of unknown behavior, they wouldn’t be standard and would break everything on a regular basis. Not the best of the world.

Then, we wrote down some specifications about what we believe would be a great addition to the footnotes. This would allow footnote, marginnotes, different kind of notes, etc. This is a bit of how would be footnotes in the ideal world, so we could engage the conversation with the folks on the w3c github. I hope that we can be back on that conversation soon enough.

But we can’t wait for the W3C to approve those specs as they would need to go through all the steps before being a real specs, thus we ended by making a simple implementation following the existing specs (https://www.w3.org/TR/css-gcpm-3/#footnotes), and we ended up with something we’re happy with.

Footnotes now exists in paged.js and can be easily set up this way:

<p>
  This is a paragraph that contains some lorem ipsum
  <span class="footnote">Fake latin</span> content
</p>

i obviously named my class footnote but you can call that whatever you want. And better, your footnote can be anything from text to table, including images or more exotic HTML (warning though, this has been tested with text first and foremost).

Then you need to define which elements need to be set as footnote using those properties:

/* define what are the footnotes elements */

.footnote {
  float: footnote;
}

/* define the position of the footnote on the page (only bottom is possible for now) */

@page {
  @footnote {
    float: bottom;
  }
}

And that’s it. You can then style the footnote callout to go beyond the user agent styles

Pay attention to the fact that there is no callout, they will be created automatically and you’ll be able to change their look with css without having to worry with the note numbering.

::footnote-call {
  content: counter(footnote, loweralpha);
  color: red;
  font-weight: 700;
  font-size: 3em;
  line-height: 0;
}

::footnote-marker {
  content: counter(footnote, loweralpha) ". ";
  color: red;
  font-weight: 700;
  font-size: 3em;
  line-height: 0;
}

You can check this codepen to see it in action.

To be able to manage the footnotes, Fred rewrote quite an amount of code of Paged.js. He made sure that the API didn’t change, but it doesnt mean that your previous content will work by default. Please test, and tell us if something goes wrong, we’ll be happy to support you.

Welcome Paged.js 0.2.0! :)

Release notes

Footnotes! (from @Fred)
Fix styles order (from @Guillaume)
White space in <pre> elements are now preserved. Hello again ascii art! (from @Guillaume)
A lot of improvement on tables from @guillaume) (Break in table with row span are now much more elegant, columns are rebuild on page breaks, etc.)
remove page border when no borders are specified (from @guillaume)
@Julie wanted to print page with a lot of colors, so she added box-shadows to the crop marks
@guillaume introduced the RenderResult object with more data about how pagedjs handle page breaks.

In other places

We now have a portfolio page. Send us a message if you want to display your work here.

One of the great thing of using the browser is to inherit all the knowledge they have: as a result, Paged.js works pretty well with content in chinese, thanks to huli.

C&F editition are working on their new collection using Paged.js but hush, it’s a surprise.

And Julien spent some time to build hooks for page float, automatic indexing, and other things we’ll be happy to show you soon. This PDF was made with Editoria. Video tutorials are coming!

Until next time!

A paged.js hackathon at EnsadLab

2021-03-18T10:00:02Z

On the 1st and 2nd of March 2021, a group graphic designers went together in Paris for a Paged.js hackathon. The goal was to bring together people who already had an experience with Pagedjs to discover how they worked, how they come to layout their content, and to think together about pushing the boundaries further. The hackathon, organised by Julie Blanc and Lucile Haute welcomed Julien Taquet, Manu Vazquez, Louis Éveillard, Sarah Garcin, Robin de Mourat and Quentin Juhel.

Despite the context of that global pandemic, we were able to meet at EnsadLab and we got lucky to have the pleasure of spending two days together.

The idea was to go deeply into how Paged.js works, to work on scripts to improve and extend Paged.js and to discuss what #CSSPrint change in terms of page layouts and new workflows for graphic designers.

We started the workshop looking at projects made by the participants. During the first morning, they showed the specific improvements they had already made to Paged.js and the difficulties they encountered in the layout rendering or in the workflows with their co-workers (authors, editors, print shops, etc.). From there, we worked on different ideas that were raised along that talk.

Generally, we have discussed and worked with handlers and hooks. The source code of Paged.js is organised in such a way in order to facilitate the addition of functionalities through the handlers and hooks. The hooks are a kind of specific breakpoint in the execution of the script that give the possibility to add your own script at different moments of the document pagination and rendering (for example before the css is parsed, and after, before the pagination of the document, before or after the fragmentation of a specific page, before and after the addition of elements in the page, etc.).

The results of the workshops are not usable as working bit directly. Some of them can be adapted to your use if you are comfortable with the use of paged.js, others still require a bit of development. All the source codes are available in a dedicated repo on our gitlab instance. In this article, we offer you a summary of the discussions and the work done.

Documentation

Sarah worked around baselines. She wrote the beginning of a documentation about it (in French): how to uses variables to fit a baseline grid, why using pixel values and instead of pt value, how to add visual guideline, etc. She also developped some scripts to automatically align elements (even images) on the baseline grid with the use of offsetTop. She went further in the experimentation by positioning the elements randomly in the page and keeping the elements aligned on the baseline.

Manu took advantage of the hackathon to document the "experiments" repo available on the gitlab. This repo contains various experimental scripts tried in the last years. Some of them are still under development and can be used for your projects with some adaptations but nobody had taken the time to document them yet. Based on his experience with BookSprints, he also works with Julie on a little script to delete content of margin boxes when an element appears on the page.

Canvas HTML for images and for drawing

Following stories of problems with offset printers with the use of CSS mix-blend-mode on some images, Robin and Louis came with the idea of using canvas to recreate the image and its effects. Beyond CSS mix-blend-mode, the use of canvas for images is a real positive point that allows a better optimization of images for printing.

Louis also worked with canvas. He made a system to inject external javascript into canevas and drawing things or downloading API. A script can be added on the fly with the data-script attribute in the canvas and the size of the canvas must be given in advance to avoid overflow problems.

Float notes

Robin and Julie works on an old script written 2 years earlier to create float notes. The script has been improved and optimized because the old version had serious problems with the fragmentation of the text content when notes was moved into floated areas. The idea is to be able to have a first implementation of a part of the draft specifications for notes proposed by the Paged.js team. These are the first foundations but there is still a lot of work to be done to achieve a solid result (so be careful if you want to use the script).

Imposition

Quentin, a fanzine lover, makes a lot of Paged.js workshops with students. Most of the time, they print their own productions and therefore need a way to impose the sheets after the paged.js rendering. With Julien’s help, he made a script to re-organize the dispositions of the pages, automaticly add pages to have a multiple of 4 and change the size of the spread after the rendering of the document. The script is only a first step and they want to develop it further to make more complex spreads (this whole idea was based on a script Julien Bidoret made).

Automatic grid layout

Louis used Potpack, a “tiny and fast JavaScript library for packing boxes of varying size into a near-square container“, to distribute image elements on the page according to their number and ratio. The script available on the repo is a good example of how automatic grid layout algorithms (for example Masonry, Packery) can be easily added to Paged.js. The idea is to start preparing javascript modules, usable with the addition of some classes in the HTML. That could be used by people who are not developers or graphic designers who do not code.

Create a link between content and pagination

During the first morning, Sarah and Julie told about the time-consuming last step of the composition of books: typographic corrections and flag management. The desynchronization of writing (on the HTML source code) and rendering (in the web browser) can make the work fastidious.

So Louis looked for a way to create a better link between the two. He imagined an interface in the browser with, on the left, the editable content as a single flow and on the right, the paginated render in a page-by-page display. The two area are linked and clicking on an item will display it in both areas synchronously. It's also possible to modify the content on the left and have it update on the right paginated rendering. This is a very good start to imagine more advanced interfaces integrating Paged.js as a tool.

Hackathon is a very interesting way of working to quickly come up with design ideas and see how to add them in paged.js. These two days were a success and we hope to find the opportunity to do other events.

Thanks to EnsadLab for the financial and logistic support, Lucile Haute for the great help about the organization, Agathe Charrel for photos and all the participants for this two wonderful days.

Avoid whitespaces on pages

2020-09-21T09:58:02Z

A long time ago, I wrote an article about page floats. Since then, we've had a lot of feedback about these CSS features that are crucial for paginated layout. We haven't yet implemented them in paged.js – because it's difficult and we need to take the time to ponder how to do. However, we are facing a recurring and urgent request regarding a specific aspect of page floats. I'm writing today to answer it :)

I'm sure you already know what I'm talking about. You know, this figure or this table that didn't fit at the end of your page? Because of how pagined medias works, if an element ends up at the bottom of a page but is too big to fit within the page height, the element is automatically pushed to the next page with a forced page break. This produces a gap, a white space, at the end of the previous page. It’s unsightly and, moreover, the reader might think that it means the end of a section.

The float properties can fix this problem, just by adding float: top and float-reference: page on the problematic element. The following figure illustrates what this should look like:

However, we can't use it today. I personally encounter this problem in some book design I make. So, based on a script made by Julien I share with you a little script to make floating-like elements in paged.js to avoid large chunks of whitespace at the end of pages. For this, we add a custom module to Paged.js using handlers and hooks.

As you can see, the script is not very long. You just have to add it in your HTML document (after the paged.js script), add the class elem-float-top to the elements where you want it to apply, and watch the magic happen.

let classElemFloat = "elem-float-top"; // ← class of floated elements

class elemFloatTop extends Paged.Handler {
  constructor(chunker, polisher, caller) {
    super(chunker, polisher, caller);
    this.floatPageEls = [];
    this.token;
  }

  layoutNode(node) {
    // If you find a float page element, move it in the array,
    if (node.nodeType == 1 && node.classList.contains(classElemFloat)) {
      let clone = node.cloneNode(true);
      this.floatPageEls.push(clone);
      // Remove the element from the flow by hiding it.
      node.style.display = "none";
    }
  }

  beforePageLayout(page, content, breakToken) {
    // If there is an element in the floatPageEls array,
    if (this.floatPageEls.length >= 1) {
      // Put the first element on the page.
      page.element
        .querySelector(".pagedjs_page_content")
        .insertAdjacentElement("afterbegin", this.floatPageEls[0]);
      this.floatPageEls.shift();
    }
  }
}
Paged.registerHandlers(elemFloatTop);

Note: It's not exactly how the float page specifications work, but it's currently the easiest way to do it with Paged.js. A real float: top on an element should move the element to the top of the page where it is anchored. However, this would mean that the text already rendered in the page by paged.js (which is before the element) would have to be pushed to the next page, causing the text to be split again. There is currently no simple way in paged.js to re-render the page if an element in the layout is moved. For the moment, this script is the easiest way to do it.

Welcome Pagedjs 0.1.42

2020-06-20T13:42:08Z

Hi there!

It’s been a while since we talked, but we have used the time wisely.

First, we were very happy to see Julie (along with Nicolas Taffin) and Fred in the line-up of the Open Publishing Fest talking about Paged.js. Their discussions and demos are pretty good examples of the use of Paged.js in the real world: Julie talked about her work on the Villa Chiragan, Nicolas focused on the ways C&F Editions are using paged.js for their new collections; and Fred showed an experiment of his, on using paged.js to render epub on the screen as fixed layout. Would printing epub be something worth having in the future? :)

Be sure to look in the archives at all the great content folks submitted to the fest.

Bug fixes and updates to paged.js

Basic support for correct borders on the page !107

We now handle border on the page as the specifications define it. The border will not be set as a border for your page anymore, but will be between the page margins and padding. If you want to have a drawn border on your page, you’ll be able to use box-shadow: inset.

Paged.js include the version in its header thanks to Guillaume (@mogztter),

Fixes for reset on page counter !128 and Fixes page counter !124

You can now reset the numbering of your page and set the number it starts from using, for instance, counter-reset: page 20. But when Guillaume starting to look at how it was supposed to work, he ended up with a tricky situation: setting reset anywhere in the CSS doesn’t seem to be valid CSS, but at the same time, it’s how the majority of all the other tools are working. We implemented a quick fix to help authors used to this way of writing css down, but we have a more in-depth article coming. Side note, you can now set up a custom increment for the page counter.

Updated page breaks on new named page !126

Guillaume also fixed a longtime bug, where a named page would create an empty page if it was the first page of the book.

Handling for nth-of-type and following (+) selectors !122, !125

Nellie McKesson, from the amazing Hederis helped all of us write better CSS by adding support for + and nth-of-type selector.

Prevent infinite loops when elements aren't placeable !118

Pagedjs used to have infinite loops when trying when an element was bigger than the page. If that happens now, it will stop the rendering on the element that doesn’t appear on the page. No more linking from CPU and RAM.

Breaking change

If one of your scripts used breakToken to move things around, make sure to test it: Paged.js now stops rendering when the breakToken is the same on two consecutive pages.

Non-significant text handling: !115

This merge request ignores non-significant Node such as a Text node that is all whitespace, or a Comment node. It also preserves Text node that does not have any sibling such as empty (<p> </p>) or Text node with a sibling (Hello <span>world</span>).
Here, the Text node after "Hello" and before the <span> element must be preserved. In this case, the textContent is updated to a single space:
Hello <span>world</span>. This fixes a couple of issues with break-after: avoid. For more information about how HTML handle white spaces, you can head over to MDN.

Add filter hooks and modules: !116

Add a filter hook that happens just before the afterParsed() one. It allows filtering the content rendered by paged.js. For now, those modules are enabled by default:

WhiteSpaceFilter: remove whitespace when possible.
CommentsFilter: remove all comments.
ScriptsFilter: remove all script elements.
UndisplayedFilter: Mark elements set to display:none as undisplayed.

Allow setting margins without units: #112

@page {size: 0 0} is now rendered correctly.

Wait a frame before handling resize: !110

Thanks a lot to Edoardo Tona (@EdoardoTona) who helped us figure out a bug in Chrome when, sometime, the pdf output is different from the screen preview (on the last part of the page) and the print PDF. By waiting 1 frame, the content is now identical.

Many great code bug-fixes: Nicholas Wylie fixed the ordered list numbering, Gregorio Roper, @garoper, fixed the issue when using page counter and custom counters, and we updated to Pupeteer 3.

Thanks to everyone who contributed. You’re amazing.

Some interresting projects using Paged.js

Maëlle Salmon made a proof of concept to make Paged.js work on the server on a Hugo website: https://github.com/maelle/testbook.
The folks at Voting Works are building open-source voting systems for US elections. One of their projects, Vote by mail, uses Paged.js to generate voting ballots: “VotingWorks Vote-by-Mail makes scaling vote-by-mail operations quick and affordable”.

And that’s it for today.

If you find any bugs, or have any questions, or want to discuss anything, feel free to join us on our chat: mattermost.coko.foundation

Notes About Notes

2020-05-13T13:42:08Z

CSS is a language that evolves by adopting new specifications. To be accepted as rules and properties published by the W3C, a proposal for new features is debated, adopted or rejected by the CSS Working Group which is made of a broad community of users, company representatives, invited experts and browser developers. Turning an idea for a new feature into an actual standard is a long process of discussion and debates in which complex cases are discussed, examples of implementations are shown, and decisions are made.

Since its third version, CSS has been divided into modules which share families of properties. Each “module” has one or more editors who coordinate community responses towards further module development. From the very first phase of writing, module discussion documents are made available to everyone interested to read them. These documents are initially known as “working drafts” and evolve towards "Candidate Recommendation" status as the community discusses and revises their ideas. Recently, the creation of the CSS Grid module has been a great example of the success of this process: the final module has been defined collectively, well written, and quickly implemented by the browser developers.

However, not all CSS modules evolve at the same speed, and even though they’ve been started a long time ago, the paged media specifications still need to be implemented in browsers, which is why Paged.js exists.

So how can we help get the page media specification process moving?

Proposing new specifications

On 13 February 2020 at XML Prague, a CSS Print Workshop took place. The workshop was chaired by Rachel Andrew and Dave Kramer, both members of the CSS working Group. Dave is also the editor of the CSS Generated Content for Paged Media Module. Paged.js team attended the workshop and were able to discuss with them how to make the specifications for paginated media and printing evolve more quickly. Following the workshop, the CSS print community group was launched, “a community of users of CSS print, working together to gather use cases, help with specifications, and advocate for more and better implementations”. This subgroup will strengthen the work of the CSS working Group by focusing on CSS for print and paged media.

The work of the W3C and the CSS working Group is easily accessed on the dedicated repo on github. During that CSS Print Workshop, Rachel Andrew described the status of the CSS Working Group, how it works and how to contribute (first part of the video). Anyone can contribute to the specifications in multiple ways: showing use cases, contributing examples and diagrams to the specifications, writing tests or even proposing some properties.

This new CSS print community group has decided to start participating in the specification as well. Our daily work with Paged.js has allowed us to develop a good knowledge of the existing specifications and also where they would need a new look. Cabbage Tree Labs, the house of Paged.js, is now part of the W3C, and as a first move, we want to propose specifications dedicated to the different types of notes that exist in editorial design.

Types of notes and pattern

The W3C specifications only allow the creation of footnotes, but designers and editors like to make use of all kinds of notes. To name a few:

Footnotes: notes placed at the bottom of the pages
Side notes: notes related to the page content, grouped in the left or in the right of the page, alongside the text area
End notes: notes grouped together in one place at the end of a document or at the end of a section of the document
Marginal notes: notes that are placed to one side of a page or both sides at the exact vertical position of the note reference number
Column footnotes: footnotes that can be placed according to the column in which they are located
Multiple notes area: not for pages that share footnotes, margin notes, column footnote, etc.

You can find some example of layouts with footnotes in a dedicated W3C page.

To make use of notes easier, we would like to propose some CSS syntax which would allow all of these kinds of notes. This article is a quick tour of a proposed specification that is described in more detail in an issue on the CSS Print Community Group repo. The article explores the existing specifications and proposes some new CSS declarations for building notes for both continuous reading (screen) and paged media. This proposal is a working draft, a place to start a discussion. Do not hesitate to give your opinion directly as a comment of this article, or if you feel more comfortable, in the issue we've opened on CSS Print Community Group.

Pattern to create notes

Notes always depend on another flow but there are out-of-flow elements, ie. it’s ancillary content that can be moved to the bottom or the side of the page or the document. A note is created when the content is moved to another specific area of the document or the page, leaving a indicator of where it was (a reference).

All types of notes are built to a similar pattern:

Declare that an element of a flow is a note.
Remove the item from the flow.
Leave a note reference indicator which points to the place the note element was moved from. This is an explicit link from a location in the document to a note element.
Place the note element and its children in a special area with all the other notes of the page or the document, in the order of appearance in the flow.
Create a marker before the note that matches the note reference.
Place the note area in the page or the document using appropriate CSS layout facilities and position scheme.
(If paged media) If the note overflows the note area, move the items to the next page in the equivalent area according to note policy.

How to tag a note in HTML ?

The W3C doesn't provide a dedicated way to tag notes in HTML. Currently, there are two most commonly used methods of adding notes:

A list of notes at the end of the document, with note references as link elements with href attributes pointing to the note using fragment URLs;
or <span> elements directly in paragraphs to encapsulate note elements in the place where they appear. This is the method used in examples in the css-gcpm-3.

After some research, reflections and a closer look at some use cases and requirements, a proposal from paged.js team has been developed to allow for this need for various kinds of notes: that there should be a new HTML tag, the <note> element which will interact with appropriate CSS to handle notes of various kinds. (This choice is more fully detailed in the GitHub issue.)

A note element represents a note, eg. secondary content that is related to other content in the document. It’s a self-contained node that gives the information about where a note starts and where it ends. The note element must be placed where the note appears in the content flow. It's the CSS mechanism proposed in this article that allows you to place the note elsewhere in the layout and to create the note call.

The following example is a conforming HTML fragment:


<p>Gutenberg  in 1439 was the first European to use movable type. Among his many contributions to printing are: the invention of a process for mass-producing movable type; the use of oil-based ink for printing books; <note>Soap, Sex, and Cigarettes: A Cultural History of American Advertising By Juliann Sivulka, page 5</note> adjustable molds; mechanical movable type; and the use of a wooden printing press similar to the agricultural  screw presses of the period.</p>

This potential new HTML element is easy to use and allows a note to be always attached to the content it adds details to. This proposal is aligned to the way HTML works (a node mechanism) without adding an HTML element that would depend on another one (to create note references for example).

Until this element exists in HTML, a span element will be used with a class named “note” for illustrative purposes.

The new CSS specifications to be proposed will allow the transformation and layout of the targeted element into different types of notes. The stylesheet provides alternate ways to organize and display notes, for specific uses and for continuous and paged media alike. In addition, the specification defines the area where the notes would be gathered / relocated in CSS if needed.

Layout the notes

Footnotes in W3C CSS specs

Let’s start by looking at what already exists in the W3C specifications. A part of the CSS Generated Content for Paged Media Module (css-gcpm-3) is dedicated to footnotes. The first section defines the terms of the footnote objects: footnote element, footnote marker, footnote body, footnote call, footnote area and footnote rule. These definitions can be applied to all types of notes. For the rest of this article, these same terms will be used without the prefix “foot” to the term footnote.

The specification also describes how to create footnotes in a page with the following code:

@page {
@footnote {
float: bottom;
/_ style of footnote area _/
}
}

span.footnote {
/_ Display span as footnote _/
float: footnote;
}

This code also creates special footnote counter and special pseudo-elements for footnote calls (::footnote-call) and footnote markers (::footnote-marker). The position, size and the styles of the footnote area are defined by the @footnote declaration. The specification does not give much indications, only a couple of paragraphs and a lot of issues and unanswered questions. The advantage is that we can do many proposals without conflicting with the current specifications.

A mechanism is needed to move the note element into specific areas of the page or the document. To do this, inspiration can be taken from a mechanism already present in the draft of the paged media specifications, the running element: by adding the position: running() declaration, an element can be removed from the flow, and reused in multiple places, perfect for the running heads of a book for example.

New proposal to create note

This proposal is for a new way to create and place notes, based on new values (note() and element()) for properties already in the CSS specifications (position and content). This could work for both media: paged media and screen.

In paged media, a new @note-area at-rule must also be added to be able to move notes from the page to a specific place. Here is an example of how it would work:

.note {
position: note(notes);
}

@page {
@note-area {
content: element(notes, all-once);
}
}

This proposal can also work for continuous media by placing the notes in a new pseudo element ::notearea that is created at the end of the declared element (just before the pseudo element ::after). All the notes contained in the element would be placed in this new pseudo element.

.note {
position: note(notes);
}

section::note-area {
content: element(notes, all-once);
}

The `note()` and `element()` functions

In both cases, the note() function declares an element as a note, removes the element from the principal flow, and makes it available to place in a page margin-box, a page note-area @note-area or a ::note-area pseudo element using element().

The element() function already exists in css-gcpm-3. It's usable in the content property of margin boxes. The proposal would see it used in the new page area @note-area or a ::note-area pseudo-element.
To make element() work with note(), a specific behaviour needs to be added that can be declared via an optional keyword all-once. The value of all the assignments of the document or the page are used. ie. all the note elements are displayed in the new area where they're assigned in the same order of the flow and have only one assignment in the document or in the page (the elements are not repeated).

The note element inherits from its original position in the document, but is not rendered there, instead a ::note-call pseudo-element is created and inserted in the original position of the note. When the note element is displayed in this new area, a ::note-marker corresponding to the::note-call is created before the note body.

Using CSS layout possibilities with the notes area

The @note-area at-rule creates special page areas that can be used to display notes elements via the element() function. The other central idea of this proposal is that any of the CSS layout facilities can be used to create, position and size note areas: float, absolute positioning, grid, exclusion, etc. Some of those possibilities will now be explored.

Put the notes in the margin boxes

Sometimes the note area doesn't even need to be declared. Using the element() function, the margin-boxes can now receive the content of the note elements. Let’s look at an example: the following rules result in the placement of the note elements inside the left-top margin box. Margin and text alignment of the note elements are set to the note element itself and padding of the margin box are set in @left-top at-rule.

@page {
@left-top {
content: element(sidenote, all-once);
padding: 5mm;
}
}

.sidenote {
position: note(sidenote);
margin-bottom: 10px;
text-align: left;
}

Use of float pages

CSS Page float specifications add some values to the float property to positioning element in a page context and propose the float-reference property to indicate the "reference container" for a floated element. Extensive use will be made of these properties in the following examples.

First, it can be used to create classical footnotes. The following code sets the default values of properties for @note-area and places notes at the bottom of the page:

@note-area {
float: bottom;
float-reference: page;
width: 100%;
max-height: 80%;
}

Using float on the page and negative margins can be helpful in creating the note area half on margin, half on text content.

@page {
@note-area {
content: element(sidenotes, all-once);
float: top right;
float-reference: page;
width: 42mm;
margin-right: -30mm;
}
}

notes {
position: note(sidenotes);
}

Since a note area is a box, it's possible to layout the area itself (with columns for example).

@page {
@note {
content: element(notes, all-once)
float: bottom right;
page-reference: float;
width: 50%;
columns: 2;
}
}

notes {
position: note(notes);
}

Multiple notes areas in a page

There are already a lot of use cases in critical editions where you can find multiple kind of notes (bibliographical references, explanations, etc.) The @note-area at-rules declaration make multiples notes easier by mixing multiple note areas in the same page context. The @note-area may be followed by a custom identifier if wanted.

@page {
@note refsA {
content: element(refsA, all-once);
float: bottom left;
float-reference: page;
width: 30mm;
margin-left: -12mm;
}
@note refsB {
content: element(refsB, all-once);
float: bottom right;
float-reference: page;
width: 60mm;
columns: 2;
}
}

note.refs-catA {
position: note(refsA);
}

note.refs-catB {
position: note(refsB);
}

In the other following example, a new value line is added to the float-reference property. This allows creation of marginal notes, i.e., notes paced to one side of the text with its first line on the same height of the flow that contains the note-call.

@page {
@left-top {
content: element(refs, all-once);  
 }
@bottom-left {
content: element(footnotes, all-once);
width: 100%;
vertical-align: bottom;
}
}

note.refs {
position: note(refs);
float-reference: line;
width: 50mm;
padding-left: 50mm:
}

note.footnotes {
position: note(footnotes);
}

Notes for multi-column layout

In a multi-column layout, note elements may have to be displayed at the bottom of each column. This means that multiple note areas might have to be created for the same fragmented flow.

Because a column is a anonymous box, there is currently no way in CSS to target a particular column of a multi-column element. This can be fixed by using the CSS Page float properties. The float-reference property indicates the "reference container" for a floated element and the value column indicates that the float reference is the column in which the floated element is placed in a multi-column environment.

This reference can be used to indicate creation of note areas in the columns of the page where the note appears. As many boxes as necessary are created on each column. All the note areas have the same properties and can be targeted by one @note-area rule only.

@page {
@note-area {
content: element(notes, all-once);
float: bottom;
float-reference: column;
}
}

#content {
columns: 3;
}

#content note.notes {
position: note(notes);
}

Here are some examples of the CSS layout facilities used to layout notes areas of paginated media. Of course, the CSS layout facilities can also be used in continuous media on the pseudo element ::area-note. Over to you to use your imagination.

This article is an overview of the specifications imagined for the notes, and is an extract from the issue published in the GitHub of the CSS print community group. That issue provides more detail than the few properties we have presented here and a few others (note policy for example). You are invited to take a look at this more complete document and comment on it. The specifications are a community work and it is only together that we will be able to improve them.

Pagedjs 0.1.40

2020-04-01T17:16:44Z

New release!

The 0.1.40 is now available to download from unpkg or npm (and on our release page).

In this release:

@julientaq added support for the position: fixed property: if one of your element is set as fixed, it will be repeated on all pages without having to struggle with margin-boxes, position: running or string-set. Be aware that the origin will always be the page, thus you’ll need to set up negative margins to your element to bring it in the bleeds.
Antonio Norman (@antman3351) found a bug and its fix, when you had multiple string elements on the same page.
Support for period in id attribute: . is for class and # is for id. But the specs allow you to use a . in an id!
Paged.js can now handle <p id="#this.paragraph"> without crashing.
@Stouffi fixed a couple of bugs in the chunker, and documented those quite well here and [there]https://gitlab.coko.foundation/pagedjs/pagedjs/merge_requests/98).
Fred Chasen (@fchasen) update the Jest infrastructure so tests are now running fine.
Guillaume (@mogztter) wanted to be sure that we’d all follow the best practices without having to spend hours checking our spaces/tabs issues, so he set up eslint, put is hands in 58 files, cleaned all the tabulation issues we had in the code and updated.

Thanks to our awesome contributors you can now enjoy this new version.

See you all very soon!

Finding letters for Atla

2020-03-08T15:53:38Z

Creating Templates is a series of articles in which one designer will explain the choices they made for a collection or a book, following the process from the typical design workflow to the output in modern typesetting using Paged.js. For the first article of the series, we’ll look at how Julien designed a template to be used in Editoria by Atla Open Press.
Established in 1946 as the American Theological Library Association, Atla is a membership association of librarians and information professionals, and a producer of research tools, committed to advancing the study of religion and theology.

Atla Open Press publishes open access books, journals, and other serials that cover subjects at the intersection of librarianship and religious and theological studies. Their books help to shape, guide and support innovative library services and enhance professional development for theological librarians and the field of religious studies.

Atla is moving its publishing workflow toward using Editoria, the community-driven platform to make books that Coko is working on. As early adopters of Editoria, Atla are an example of how you can change your publishing workflow by giving more space to collaboration with anyone involved in the making of the book. As part as their collaboration with Coko, Julien worked with the folks at Atla to design a template to be used in Editoria, ready to be used with Paged.js. Atla have now offered the template back to the community with an open source license (the template will be released soon).

The physical book

The primary form of the books published by Atla Open Press is digital: epub and PDF made for the screen, and the books are downloadable from their website. But the books are also produced as printed material, using Print On Demand services (or personal printers).

When the team started to work on the template, we explored an array of potential final output sizes for the book, and eventually we decided to go with a standard 6 × 9 inches (15.2 × 22.8 cm). Following the standard reduces the risk of errors when working with different printers, and if the reader needs to print the document at home, it’s pretty easy to put 4 pages per sheet of paper, reducing the waste without losing too much readability.

Once you have the size of your book, you’re ready to work. But what happens next is never a nice and easy sequence of steps to follow. It’s more like a series of trails and paths that we follow at the same time: fonts, font-size, leading, margins, etc. This production process is where the tension between aesthetics and readability has to be taken into account.

The first step is to figure out the number of characters which can be put on a page. The number of characters per line is the element that will determine a great part of the layout, so it needs to be carefully considered. Most books for scholars allow for more than the 55/65 characters per line usually advised for ebooks. With that in mind, letter choice can begin..

The typefaces

Typesetting is the act of putting letters on paper in a way that gracefully mixes legibility and aesthetics. Therefore, it starts with drawn letters. Always.

Here is a useful checklist:

Remember the kind of letters you’ll need to work with.

How many of letters outside of the Latin glyphset will you need? Is your content only English, or do you have letters from extended Latin, or Greek? What about Cyrillic? Does it include a section of an old transcript from oral languages that has just been included in the Unicode? Since the books Alta publishes are about theology and religions, it’s not gambling to say that there will be a lot of non-English characters.

Remember every member of the family you’re going to need

Sometimes you need to emphasise one part of the text, or show that a word has a different meaning or comes from another language. While an emphasis is not always set as italic, that has become over the year a kind of a standard: the em HTML element for the emphasis is by default an italic in almost all browsers.

Therefore, Roman letters are not enough for this template. So you need to be sure that the letters will have those styles available. Italic is the minimum. Bold is seldom used for emphasis in ebooks as it’s often not subtle enough, but it’s always useful to have that option for headers and structure.

Remember the type color

Whatever font you choose, you’ll need to have the right balance between white and black on the page (ie the type color). That balance depends on how the type is set up: the drawings of the letters, the number of characters per line, the options for the justification: spacing, kerning, the width of the white space, etc. Depending on the content, you may want to have a darker feeling, that your page is filled with content, or you may want to be precious and have a lot of white space, giving a feeling of luxury. A good type color is one that is not too black, not too white, and dynamic enough to never feel grey.

Remember that the look of the book is different than the experience of the book

I think that Tarantino said once that he never watched a movie without knowing it was a movie. I can say that I have never read a book without knowing it was a book: my designer’s eyes always get the over all feeling first: the type color, the font chosen, the margins, the alignments, etc. I understand the book before I start reading it. But here is the trick: a book can feel well designed and perfectly crafted, but the experience you’ll get from its reading may be different. So don’t forget to print and test and have a good look, print again, check again, until you’re happy with the feeling as much as the look.

Choosing the right fonts

As a designer, I used to follow every link that led to a new typeface or a new foundry. I bought fonts just because I liked their look even if I had no clue about how I would use them. So I got to look at fonts all day long, teaching my eye to look for specificities and to remember the feelings those could give. Choosing a font is all about finding the tiniest bit of the letter that will give the first impression on the book.

In Atla’s case, my first idea was to look at the classics. Going with a well-known letterform will give a sense of trust and truthfulness. But at the same time, I wanted to find something that was representative of the personality of the publishing house. Warm and friendly. Serious and friendly, the people you want to work with. And then also, there is the need for the font to support a wide range of letters and glyphs, and that’s generally the place to start.

I started by looking at what I knew would answer that question, first choice being the Brill typeface, designed by the folks at Tiro Typeworks. Significant factors were firstly, because it supports Latin, Greek and Cyrillic, and secondly because each letter has been designed with care. However, you can’t really use that font for an Open Source project: as the Brill end user license agreement specifies that the font can only be used in a non-commercial environment, so that rules out using it for Atla.

Thankfully, over the last 20 years, there has been a lot of movement in the world of open source type foundries, and there is even a specific license, the SIL Open Font License (OFL), in use since 2005. I decided to investigate what the foundries offered, and I have spent a good deal of time finding what is available and identifying what would be a good fit for Atla.

The font library is often a good place to start looking for open source fonts. It includes a CDN that let you test your fonts in your files without having to build any @font-face functions. Language support generally needs to be a priority especially for as much of the Latin as possible, and the more languages the better, starting with Greek and Cyrillic, as they are often designed with the same tools and movements as Latin is designed with. Most of the time when you look at your content, the letters coming from another language will fit right in place.

EB Garamond

First, the classic of the classics, the Garamond, but the one under OFL licence, EB Garamond. The glyph set and the open-type features are quite interesting. These are in optical sizes: you wouldn’t use the same glyphs for a text set in 12pt or for a text set in 10pt, which is a tremendous work. But there is one caveat: there is no bold, so that would leave less options for the headings structure.

The other issue with the Garamond is the hardness of its shapes: the plume and the calligraphic gesture behind the letters survived in the digitization of those letters. While this adds a lot of authority to the letters, it doesn’t give the warmth and kindness I am looking for.

Noto Serif & Linguistics Pro

Noto fonts is an attempt from Google to have one super font family that supports all languages ever written with the same look and feel. While this seems to be an impossible task, Noto fonts already supports a wide variety of languages, which makes it a pretty good starting point to show international content. For example:

A font is like a color: it carries a lot of feeling in itself, but to have the most complete overview of its specificities, you need to compare it with another. So I you need to check the foundries.

The other font I looked at was Linguistics Pro, the most recent take on the Utopia Nova. The story of those letters goes back to 1989 when Robert Slimbach designed the font for Adobe and licensed to the TeX Users Group (TUG) for free modification and redistribution. Over the years, it has evolved to include polytonic Greek, modern and traditional Cyrillic, Vietnamese, among others, and was re-released in 2016 by Stefan Peev. It includes italic, bold and bold-italic, which is useful for headings.

While the two fonts feel close over all in look and feel, they turn out to be very different when you inspect them carefully:

Noto Sans is more friendly than Garamond or Linguistics. It’s a modern serif that brings back a lot of manual gestures: the terminals of the f, r or capital S are all about calligraphic feelings, while the mechanical serifs are all about math and geometry. Those two characteristics are pretty useful when it comes to sharing shapes between letters from different parts of the world.

Linguistics Pro, on the other hand feels less modern. It’s based on a character that could have been released at the end of the 18th century when typographers were slightly moving away from their calligraphic roots to enter the world of rationality that was coming. Thus, we can find in those font characters, the characteristics of a scientifically drawn letter and the humanity of rounded serif terminals, never being sharp: a friendly but trusty face.

The last step is checking the fonts in context of a real paragraph, using text you can actually read, and no lorem ipsum placeholders.

The sizes of the letters are different: the Linguistics Pro family has a bigger ratio between the ascenders and the x-height than Noto. This gives a lighter feeling: the text will need less leading to achieve a good type black, and we’ll have more lines of text per page, which is a huge win when it comes to monograph books: reducing the amount of paper needed without losing readability is the real thing we’re trying to achieve.

So let’s try Linguistic Pro first, and we’ll see if we need to change later on.

Spoiler: it works fine.

The next article of the series will be all about the amount of content we can put on a page, defining margins, headings, and page types. See you all very soon.

Welcome to paged.js 0.1.38

2020-02-25T11:25:19Z

New in this release:

Somehow, the release has been made before the code for the string-update feature was merged. Since the release , it will be part of the 0.1.39. If you want to use that code today, you can download it from here

This is a minor release which includes one item:

updated our support for the string-set property. Following the W3C specs, you have now more options to define which title will appear on the page. Here is the schema that helped us implement it, courtesy of Julie Blanc.

Additional items:

Thomas Parisot and Fred set up an automated workflow to publish new versions when the gitlab codebase is updated. This will help us provide better support to the people who implement Paged.js in other tools or workflows.
Pagedjs-CLI (now in its version 0.0.10) is updated to support post-processing PDF. As a first feature, we’re now able to define the crop box and the margin boxes of the PDF. Also if you use the CLI your PDF will now be tagged!
We’re also documenting the roadmap for the coming months to give you a better overview of where we’re going, and how you could help if you want to. We’ll share it soon!

Updated Documentation

We have updated the list of the Paged media features that paged.js supports. It contains links to some examples we made and to the W3C specifications. You’ll find everything in our documentation. Please drop us a line if something is unclear, we’ll be happy to make a tutorial for it.

Hugo Component

For those who never heard of it, Hugo is an open source static site generator written in Go, blazing fast and pretty efficient. It’s packed with a ton of features and ideas so smart that building the paged.js website with it has been a pleasure. One of the features we need for the website is Paged.js integration to make books out of the HTML. Thus, we made an implementation of Paged.js for Hugo. Hugo has a really well thought out theme engine: to be able to use the print script you only need to add the information in your config theme, et voilà. It’s still early and experimental, but if you hit the top right button on this page, you can see what it does. Feel free to raise a GitLab issue if you find any.

Paged.js on Reddit

Last week, we were mentioned on Reddit! We ended up answering some questions as an improvised Q&A session. Since keeping track of things on Reddit is not easy, here are a quick overview of some questions and our responses.

From /u/HarmonicAscendant

“I am wondering how it could best work with markdown > pandoc to HTML > paged.js to PDF with Chromium”.

Paged.js is a js library, you can use it in any workflow :) For instance, the paged.js website is developed using Hugo, documentation is written in Markdown, and the result is a website, to which we added a button to run paged.js, preview the book in the browser and make a PDF by printing the page. And yes, using CSS for the layout is easier than going with Tex :) You can make a PDF with any HTML source :)

From /u/ebichuhamster

“Isn’t this a thing already just using css?”

It should be. W3C wrote (and keep writing) a lot of specifications for print, but browsers haven’t really implemented those. That’s why we’re making a polyfill: you can write the CSS following the specifications even if they’re not implemented yet and call Paged.js to transform those into rules that our browsers can understand today. When the browsers will have implemented all the things we need, we’ll stop working on Paged.js (but don’t expect to see that to happen in a near future).

From /u/brainbag

“Could you say more about how you implemented this? We're using puppeteer to render PDFs server-side, but I've been waiting for client side css to have better handling so we can drop it.”

You can check the not so-well-hidden button top right here to see Paged.js in action. It will run paged.js, show the preview in the browser and offer you to print as PDF. Client side PDF rendering! A small warning though: Chromium and alike are the only browsers that let you print in custom paper size (A5, Square, custom, etc.). In the case that you’d like to set the page size at A4 or letter, you’ll be safe in almost every browser.

From /u/dhimmel

“[What about] Numbering pages on the output PDF”

This is pretty basic Paged media specs stuff, we got you covered in the doc. (you may want to read from the top of the page though) https://www.pagedjs.org/documentation/07-generated-content-in-margin-boxes/#page-counter

“Numbering lines on the output PDF”

A solution build by the community: https://github.com/rstudio/pagedown/issues/115 I’ll make a post about that. We also have a simple solution to build a baseline grid: https://www.pagedjs.org/images/linecount.png

”Floating figures and tables to avoid large chunks of whitespace”

We do have solutions to do that, but it depends on your content and how you want it to behave. Floating top is pretty much easy to do. But Julie, our specialist of specifications wrote quite a good article about that: https://www.pagedjs.org/page-floats/

“multiple columns on PDF pages”

Yes sir :) We’re using the browser and pages are made using css grid and flex, so you can do pretty much what you would do in a browser for screen. I’ll try to find some examples in the coming days.

From /u/Serei

“Is it possible to make footnotes that appear at the bottom of the current page?”

The W3C specs for the footnotes are still being finalised, but we are actively working on some solutions to follow these specs (even joining the w3c print working group to make those evolve). We have some solutions for margin notes https://gitlab.coko.foundation/pagedjs/experiments/tree/master/margin-notes and we made a couple of books with footnotes, but it needed some manual works to make sure the layout was great.

We’re now upgrading the library core to handle multiple flows and float-top and bottom, which would allow us to have footnotes, and ones that would run on multiple pages if needed. We’ll make an article about that soon.

One more for the road

The excellent Hugo “Kitty” Giraudel made a tool to turn any CSS selector into proper English. If you don’t understand why your CSS properties are not being applied, or if you only want to get better at targeting elements with precision, this is the webpage to consult: https://hugogiraudel.github.io/selectors-explained/. It also includes the selector specificity score.

And that’s all for this time folks, but we keep working.

Stay tuned!

Return from Prague: the future of web to print

2020-02-18T11:02:48Z

Report about the W3C Workshop on CSS Print

On Thursday, February 13th, a group of people gathered at the University of Economics in Prague (Czech Republic) to participate in theW3C Workshop on CSS Print as a part of the XML Prague conference. The event was organized by Rachel Andrew, Jirka Kosek and Dave Cramer, members of the CSS working group. Between 30 and 40 people were present, showing a real interest in CSS print.

The workshop started with a presentation by Rachel Andrews, talking about the work of the W3C about the creation of freely open standards for the Web and how the working groups operate, particularly the CSS working group. Rachel recalled that standards take time to set up, because of the specification process, but also because of the lack of funding for work on print specifications. She enumerated a list of possibilities for making things better. Anyone can and is allowed to contribute to specifications (no need to be part of W3C or need permission). Reading and commenting on specifications issues is a good start, as is showing use cases or developing web platform tests. It's also possible to contribute by providing examples and diagrams to specifications. If we want the specifications to improve, there's no secret; the W3C needs to find people to work on print-related specifications, testing and implementations.

After Rachel, several people who had submitted their paper positions, gave shorter presentations about their work and the tools used with CSS print and paged media.

Dave Cramer started with his work at Hachette Group. Hachette have produced (many) PDFs with HTML and Print CSS over the last ten years. He also talked about the fluctuating implementations of paged media and generated content for paged media in web browsers.
Michel Miller presented Antenna House and their custom AH formatting engine used to make CSS and XSL-FO paged media outputs.
Cornelia Kremlin and Katharina Udemadu presented Compart, a supplier of document and content technology solutions. Compart is working on the creation of transactions documents using data from an XML data source to create multiple outputs, including PDF.
Andreas Jung presented his print-CSS. Rocks project, a website where you can find information about tools that exist to create PDF outputs from HTML or XML content. The project offers tutorials and lessons and compares tools and implementations through small, simple tests.
Liam Quin spoke on a more general level about why pages matter in apps and websites and should be taken into account. He reminded us that the things that people need today are not only about pretty output but more importantly about functionality (initial caps, indexes, marginalia…).
I also presented Paged.js, how the library works and our position in relation to browsers and needs.

All the presentations talked about CSS pain points, print requirements, and some useful specifications that are not yet implemented in any browser or tools (such as handling the initial letter, for example). There is a real need and there are still too many things we can't do today. A lot of specifications are missing in browsers and tools and adoption of the standards is slow. Many tools also develop their own specific extensions to meet the needs of their users (such as page float, footnotes in multi-columns…) and the compatibility between tools is limited. In short, there is a huge amount of work to be done for full use of CSS print and CSS paged media.

A one-hour discussion involving all participants followed the presentations. Some questions which had been raised in the presentations, came up repeatedly:

What are the missing parts and what can we do? How can we identify relevant features missing in Print CSS? Footnotes or mixed writing modes were often raised as examples where more work is needed.
In the existing specifications, how can we best prioritize the various needs of implementation? For example, there's some low-hanging fruit, and things Web developers will find useful (e.g. CSS exclusions), maybe we should start with that, because there's going to be strong interest in that.
Another example, @page size bug is a major issue in some browsers, impossible to hack, if we don't start there, the rest might be for nothing.
You can also see other questions and points by reading position papers and/or the transcription of the conversation here.

To date, the specifications for print/paged media have been developed under the flag of the (CSS WG). The group also works on a lot of other things; print and paginated media are not necessarily its priority. The work in this area is lost in the mass, not very visible, and the status of CSS draft specifications are unclear (unmaintained, work-in-progress, discontinued?) For example, Dave Cramer is now the only editor of generated content for paged media module and needs help. Writing layout specs is hard, and we need to figure out how to get enough people to contribute

So, during the final conversation, rather than make a wish list of new specifications, we focused on the process: how can we work more effectively with the CSS working group (CSS WG)?

As Liam Quin said in the conclusion of his presentation, "nothing will go forward until the stakeholders are proactive." During this workshop, we could see that there is a core of people very interested in what's going on today with CSS for print and paged media. At the end of the workshop, a new community group was established as a place of our own to raise issues before bringing items to the CSS working group. Dave Cramer, supported by some of the participants, proposed this new group be added to the W3C as the CSS Print Community Group.

The purpose of the group is to “work together to gather use cases, help with specifications, and advocate for more and better implementations”. At the end of the day, the community group was launched and accepted in the list of the current W3C community group: https://www.w3.org/community/cssprint/. You don't need to be part of W3C to join it, so jump in!

Our position paper for the W3C CSS print workshop

2020-02-14T10:19:56Z

Paged.js

Position paper for the W3C Workshop on CSS Print (February 13th, 2020)

Paged.js is a free and open source JavaScript library that paginates content in the browser to create PDF output from any HTML content. It was developed to meet the requirements encountered by Adam Hyde, Fred Chasen and Julien Taquet when building the book production platform Editoria: an open source solution was wanted and there were no existing solutions which did what Editoria needed. Right around that time, Julie Blanc joined the team and the four of us built it together.

Adam has spent years on helping organizations to define their own publishing workflows, and building publishing platforms. Fred has been working in the publishing field for quite a while and his work on epub.js has proven invaluable. Julien has been producing books with html and css for more than five years using a variety of tools, either at Book Sprints Ltd or for Coko. Julie was working on her PHD on evolution of design in typesetting and she was able to focus her research on the specifications which would be needed for the Paged.js project and how they might evolve.

Before the team jumped into the work, we decided to discuss the project first with the people in the field, and in January 2018, we organized the first such meeting at the MIT Press in Cambridge (MA). We were able to share our experience, examine existing solutions and share some of the experiments Fred has been working on.

Subequently, we started the next stage of development armed with the knowledge gained from that community meeting.

Paged.js: a polyfill for print specifications

Following the Paged Media standards published by the W3C (ie the Paged Media Module, and the Generated Content for Paged Media Module), Paged.js acts as a polyfill for the CSS modules to print content in ways that are not normally supported by browsers.

The technical bit behind Paged.js

When Paged.js starts on a webpage, it reads the HTML content and the CSS rules defined in the links or the header, and starts the paginating work by modifying the DOM structure, adding HTML elements to build pages, and translating the CSS to render the layout. The HTML source doesn’t need any specific properties or elements, as all the layout is defined in the CSS.

The library interprets the declarations and translates them into CSS and JavaScript, either by converting them to common CSS styles or by replacing them with JavaScript implementations. To achieve this, the page model from the Paged Media Specifications has been rebuilt using grid and flex-box, and since we use the browser to render our pages, we can leverage all the work put into implementing other CSS specifications such as flex-box, grid, svg management, etc.

Three modules

Paged.js is made of three modules that work hand in hand:

the chunker that fragments the content into discrete pages,
the polisher that transforms the CSS declarations into ones the browser understands
the previewer which shows how the book will be printed in the browser.

The chunker

The chunker is the part of Paged.js that manages the fragmentation of the content to flow it into pages. To do so, it takes all the rendered content (with their css styles), creates a page (following the page model of the specs), and pust the content in the content area.

To find where the content needs to be fragmented, CSS-columns are used: each page is a column with width and height set to be exactly as the page content area will be in the paginated output. Once an element overflows the page height, a new page is created, and the rest of the content goes in. The chunker keeps doing that until all the content is laid out. Once the script is done, the content area of each page is an independent HTML element. Using CSS columns allows easier access to the fragmentation properties already implemented in browsers, such as page-breaks, element properties, or widows and orphans.

The polisher

Thanks to the CSStree library, the polisher parses the CSS and translates the CSS stylesheet into classes that the browser understands. For example, the properties of the @page rules are turned into HTML classes. In other words, you provide CSS that conforms to the standards, and Paged.js applies those on the transformed DOM.

This way, the system is able to handle running headers, page counters, or any CSS-generated content functions with CSS custom properties from the DOM. Paged.js also adds references to every node (for example, data references to find elements that are split between pages). This gives a complete control over the page layout and users can access these elements in CSS or Javascript with their classes if they want to go further with Paged.js and add their own functions.

The previewer

The previewer makes it possible to have a visual preview of the printed output directly in the browser with a graphical interface. This allows designers to access development tools to make changes and control the rendering of the composition. Using simple css properties, pagesare shown as facing pages, single ones on top of the other, the same way you would see those in the classic book design applications.

But Paged.js can also be run in a fully automated workflow where the PDF is generated server side. This makes use of a command line version of Paged.js based on Puppeteer to open a Chromium headlesss instance and create the PDF files.

Plug into paged.js

Paged.js is a modular library that runs each part of the code in a specific sequence: from the parsing of the content and styles, when a new page is created, when a new element is added on the page, when a page has finished rendering, to when the library has finished its job. This lets you add any custom module you may need. For example, to set the image as page-float: top you can follow this simple algorithm: when a img or a figure element gets rendered, remove it from the flow, and prepend it as the first element on the page. The same idea can be used to create a baseline rhythm where you can add padding-top to element which are not starting on the grid.

A community

For the last two years, the Paged.js project team has put a lot of effort into keeping the community informed and engaged. We regularly meet for a Mattermost chat with around 150 people, where we discuss issues, report on updates, code and plans for the various projects that are using Paged.js.

Projects

Coko’s Editoria is the first project to include Paged.js export. With the developers, we’ve been working on providing support to explain how the library works and how they could add a templates manager, live update of the export when the css changes, etc. The users of Editoria are publishing houses who have a high expectations when it comes to the pdf output, and that offers us a wide variety of use cases.

Pagedown is another interresting project that uses Paged.js to generate PDF for the Rstudio community. RStudio develops free and open tools for R, and enterprise-ready professional products for teams who use both R and Python to scale and share their work. Romalin Lesur and Yihui Xie have been advocating for HTML and CSS instead of Latex, and the monthly download numbers are pretty high.

Hederis, a platform to design books and publish PDFs uses Paged.js for previewing and updating the books. Hederis project founder Nelly McKesson was part of the Cambridge meeting and came to meet us during an Editoria event in San Francisco last year. She’s also contributing to the project codebase.

AsciidocPDF is a PDF converter for AsciiDoc based on web technologies. It allows complex layouts to be defined with CSS and JavaScript, while writing the content in AsciiDoc. Guillaume Grossetie and Thomas Parisot who are maintaining the tool are actually contributing back to Paged.js, offering us a tremendous help.

PanWriter and Ovide also use Paged.js, and we’re discussing developments with Stylo, and others projects we’re helping.

Julie Blanc also worked on the Villa Chiragan project that presented sculptures of the museum on the web. You can check the printer version if you print on any webpage, and you can also check what she managed to do using Paged.js here.

Workshop, teaching and lectures

Since the beginning of the Paged.js project, the team has been part of a number of different events to introduce paged.js, from publishing events (such as the digital publishing summit in Paris) to open source meetings and conferences (Write the docs at Mozilla's office in Paris, journées du logiciel libre in Lyon, Fosdem, etc.) to present the project, or to discuss with other members of the community.

We also spent quite some time organizing workshops and meetings to show Paged.js to editors and designers. Many workshops also take place in art and design schools so that future professionals are trained in these ways of doing. We hope to do more in the coming months and years.

By providing more examples of what can be accomplished using print CSS, we hope to advocate for better support of print-related standards in browser engines. It's our first goal, until then we will provide support via our work.

During the second half of last year, we rewrote the documentation, and made a new website (we’re working on it and hope for a release pretty soon). You can have a quick preview here to have an idea of how it will be. We’ll also provides templates, insight into Paged Media specs, and use it as a platform to write for anyone who'd like to write a piece about what we're doing. We’ll also reprint some of the articles from www.pagedmedia.org as a way to highlight that information.

Following the same idea, the repository for Paged.js also contains some examples which provide insight into how to build a table of contents, how to follow a baseline snapping layout, or use hooks, and even a first implementation of the footnotes.

The future of Paged.js

As we now have a more mature library, we have stared to look at where we’d like to go with Paged Media. Therefore, as the time of writing this, we’re joining the W3C under the flag of the Cabbage Tree Lab as we want to be part of the continuing standards conversation.

Julien is now working on the community side of things, organizing events and fixing issues, keeping everyone happy while the codebase evolves. Julie is writing new specs ideas that we’ll hope to share and discuss as soon as possible. Fred is rewriting the whole chunker, as we’d like to support multiple flows, floats and offer a better footnote solution than the one we have now.

When this is done, we’ll layout a roadmap (more like a subway map) so anyone can contribute where they think they can best do so. Members of the community are also starting to offer services to those who may need custom development or specific stylesheest, as more and more users are getting confortable with designing books in browsers.

We welcome you to join us!

Build An Index With Pagedjs

2020-02-02T14:40:08Z

Download the script here: https://gitlab.coko.foundation/pagedjs/experiments/blob/master/book-index/js/createIndex.js

Preparing your HTML

In the simplest terms, a book index is simply a key to locating information contained in a book. The main idea of the book index is to help the reader find information quickly and easily. It is not a way to locate in the book all the paragraph where the word "music" appears but to locate the places in the book where the word music is "revealing" in relation to the content. In this way, create an index is a semantic work that cannot be done automatically.

When you think your content is revelant and need to be in the index, simply add a span around the content:

<p>
  General definitions of
  <span class="book-index" data-book-index="music">music</span> include common
  elements such as pitch, rhythm, dynamics, and the sonic qualities of timbre
  and texture.
</p>

Your span must contain at least two elements:

a class: this class is common to all index span elements of your document, you can name it as you wish
a data attribute: this data attribut must be named data-book-index, it indicates the word(s) that will appear in the index
you can also add an id if you want but it's not required

About the data attribute:

all data attributes containing the same word will be combined in a single line in the index, so you can use the same data attribute several times in your document
it is possible to use spaces, capital letters and dashes in the data attribute, like this for example: data-book-index="Wolfgang Amadeus Mozart"
it is also possible to format the text with the <em> en <i> elements (only): data-book-index="<em>String Quartet in C major</em>"

Finally, you must add somewhere in your HTML an element in which the book index will be generated. It can be a section or a div but it must be indicated by an id (that you name as you wish):

<div id="book-index"></div>

Use the script with paged.js

Add the async property to the paged.js script:

if you use paged.js with npm: <script async src="http://localhost:9090/dist/paged.polyfill.js"></script>
if you use the online script of paged.js: <script async src="http://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>

Add the book index script:

<script src="js/createIndex.js" type="text/javascript"></script>

Call the book index scripthtml

The book index need to be generated before that paged.js fragmented the content into pages. You need to the hook before to call the script.
Add this code in the head of you html document:

<script>
  window.PagedConfig = {
    before: function () {
      createIndex({
        spanClassIndex: "book-index",
        indexElement: "#book-index",
        alphabet: true,
      });
    },
  };
</script>

Use the print CSS properties in your stylesheet file to target the pages where the index elements appears:

.link-page a::after {
  content: target-counter(attr(href), page);
}

.link-page::after {
  content: ", ";
}

.link-page:last-of-type::after {
  content: none;
}

.index-value::after {
  content: " – ";
}

Configuring the script

spanClassIndex: define the id element where the toc list will be create
indexElement: define the id element where the toc list will be create
alphabet: choose if you want the alphabetical elements (true) or not (false)

Styling the book index

The script generates a list with items you can style. Here is an example of a book index generated:

<ul id="list-index-generated">
  <li class="list-alphabet-element" id="alphabet-element-A">A</li>

  <li class="list-index-element" data-list-index="Apple">
    <span class="index-value">Apple</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-10"></a></span>
      <span class="link-page"><a href="#book-index-23"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Apricot">
    <span class="index-value">Apricot</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-15"></a></span>
      <span class="link-page"><a href="#book-index-35"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Avocado">
    <span class="index-value">Avocado</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-19"></a></span>
    </span>
  </li>

  <li class="list-alphabet-element" id="alphabet-element-B">B</li>

  <li class="list-index-element" data-list-index="Banana">
    <span class="index-value">Banana</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-2"></a></span>
      <span class="link-page"><a href="#book-index-38"></a></span>
      <span class="link-page"><a href="#book-index-12"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Blackberry">
    <span class="index-value">Blackberry</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-17"></a></span>
      <span class="link-page"><a href="#book-index-24"></a></span>
    </span>
  </li>

  <li class="list-alphabet-element" id="alphabet-element-C">C</li>

  <li class="list-index-element" data-list-index="Cherry">
    <span class="index-value">Cherry</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-32"></a></span>
      <span class="link-page"><a href="#book-index-27"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Coconut">
    <span class="index-value">Coconut</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-41"></a></span>
      <span class="link-page"><a href="#book-index-8"></a></span>
    </span>
  </li>
</ul>

An example of CSS to styling the book index:

#list-index-generated {
  list-style-type: none;
}

.list-alphabet-element {
  font-weight: bold;
  padding-top: 18px;
  padding-bottom: 9px;
  font-family: Arial, Helvetica, sans-serif;
}

.index-value {
  display: inline-block;
  min-width: 120px;
}
.index-value:first-letter {
  text-transform: uppercase;
}
.index-value::after {
  content: "none";
}

.link-page a {
  text-decoration: none;
  color: currentColor;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 12px;
}

Paged Media approaches : page floats

2020-02-01T21:24:56Z

Layout is the operation of positioning and styling elements of content in a given space. It aims to position the content (text, images, notes…) in a hierarchical and harmonious way (balancing the zones, colors and spaces, contrasts), in order to facilitate display and the flow of reading.

Layout is more complex than the flow of content from one page to the next with appropriate elements of stylization. Each page must be balanced and provide for pleasant reading. To achieve this, we need to position elements in relation to the flow of text but also in relation to the page as well. Elements will have text wrapped around them to manage a pleasing allocation of white space and avoid creating widows and orphans.

In CSS specifications, the float property is very interesting. The property indicates that an element is to be removed from the normal flow and instead be placed into a different place – currently, on the right or left side of its container. Text and other inline elements will then surround the floated element.

In its simplest use, the float property can be used to wrap text around images. This property can take four values: left | right | inherit | none.

New properties (float-reference, float-defer) and values (for float and clear properties) have recently been proposed in the W3C working draft CSS Page Floats. These properties add further ways of refining layouts and that’s what we are going to look at in this post. We also propose additional new extension values, based on what has already been proposed in proprietary tools such as Vivliostyle, Prince, PDFReactor and AntennaHouse.

Paged.js is not yet supporting page-float, this article is there to help define the implementation and the future work.

Float reference and float properties

The float specification first needs to be established in reference to some default value or position. e.g. “The entity to which the float is aligned initially before float placement takes place” (CSS Page Floats).

To do this, we need two properties:

float-reference allows the definition of a specific entity as the reference to which the element is moving. The float reference can be the float anchor’s line box, column, region or page; and
float is used to specify where the element will move in relation to this new reference.

A simple example will make this clearer. In this example, initially, a figure is positioned around the middle of the page. We want to move the image to the top of the page. For this, we define the page as our float reference and we use the values top as following :

figure {
width: 100%;
float-reference: page;
float: top
}

The float property (W3C specifications)

There are two types of values that I separate into two categories I call “floats XY” and “floats AB”.

Floats XY

left | right | top | bottom

These values are interpreted relative to the page, independently of writing mode. Their physical directions correspond to the x-axis (horizontal dimension) and y-axis (vertical dimension) of the page.

Floats AB

These values are interpreted relative to the flow of content. There are abstract directional and dimensional calculated directly from the values of the writing-mode and direction properties.

These flow-relative directions, block-start | block-end | inline-start | inline-end, are defined in the W3C recommendation CSS Writing Modes Level 3 as follows:

block-start : “The side that comes earlier in the block flow direction, as determined by the writing-mode property: the physical top in horizontal-tb mode, the right in vertical-rl, and the left in vertical-lr.”
block-end : “The side opposite block-start.”
inline-start : “The side from which text of the inline base direction would start. For boxes with a used direction value of ltr, this means the line-left side. For boxes with a used direction value of rtl, this means the line-right side.”
inline-end : “The side opposite inline-start.”

So, the block-start float value gives a different result if it’s applied to elements contained in an entity with different writing-mode and direction properties. According to the specifications of the W3C working draft CSS Page Floats, with the block-start float value, “the element generates a box that is floated to the line-start outer edge of the float reference. Content flows on the line-end side of the box.” This gives the following results:

Avoiding white spaces

It often happens that an element ends up at the bottom of a page but is too big to fit within the page height, so the element is automatically pushed to the next page with a forced page break. This produces a gap, a white space, at the end of the previous page. It’s unsightly and, moreover, the reader might think that it means the end of a section. The float property can fix this problem.

In the following example, the figure is already at the nearest edge, so it does not move. However, floats allow subsequent content to be displayed before the float and the white space can therefore be filled.

Note that in Prince, the proprietary optional modifier unless-fit is to be used in combination with other float instructions, and is conditional: the element is only floated if it would otherwise cause a page.

element {
width: 100%;
float: top unless-fit
}

The snap-block value

The snap-block(<length> [, start | end | near ]?) value and the snap-inline(<lengtht> [, start | end | near ]?) values specify than an element floats to the start or the end of the block if it naturally appears within a certain distance from either one.

The length value specifies the reach of the snap function, e.g. the maximum distance from the start/end that an element must be within in order to be floated.

“The length value specifies the distance from both the start and the end, two length values specify the distance from the start and end, respectively. The optional keyword value specifies where the element is floated: start, end, or the nearest of the two. The initial value is near. If near is in effect and the element is within the specified distance both from the start and the end, end wins.” (W3C specifications)

In this example the first element is affected, but not the second :

element {
float-reference: page;
float: snap-block(2em near)
}

An element with the snap-block() value is considered to be a float even if the element does not appear within the specified distance. In this case, the element floats at the start / end line, but not at the start, nor at end of the block.

The snap-block and the snap-inline values correspond respectively to snap-block(2em, near) and snap-inline(2em, near). It can be very useful to apply this float property to move an element to the top of the next page unless it fits on the current page without causing a break and leaving a gap, or without causing a widow or orphans.

Extensions proposals for pagedmedia specs

Although the W3C draft extends the possibilities for float values, they are still limited and some layouts are still not possible. In this part, I want to propose new extension values, sometimes based on what has already been proposed by some proprietary tools.

Combinations of XY directions

In the W3C draft, there is currently no way to float into a combination of directions (top right, right top, left bottom, bottom left, etc.) but it’s possible in Antenna House. For example, with float: bottom left, the element goes to the left bottom corner of the page. It’s a very interesting extension which allows more possibilities for layout.

Inside and outside values

The values inside and outside are very useful in print because we often have to deal with left-facing and right-facing pages, together forming a spread. These values can be found in Prince or AntennaHouse and are interpreted relative to the page (floats XY), moving the elements respectively to the inside or outside of a spread:

with the inside float value, an element can be floated at the left side on a right page and at the right side on a left page.
with the outside float value, an element can be floated at the right side on a right page and at the left side on a left page.

After and before

The values after and before are a new proposal which can be added to the list of floats interpreted relative to the flow of content (floats AB). They indicate that the content flows respectively on the block-start and the block-end side of the box. These values can be used in combination with the other “float AB” values to force the side of the content flow.

UPDATE (7/04/2018)

Shinyu Murakami (Vivliostyle) noted in a comment of this article that after and before keywords were used in the W3C’s old logical (flow relative) direction terminology (W3C XSL-FO). inline-start and inline-end would probably be a better choice of keywords and fit closer the new W3C logic. We will adopt this terminology for the future. In the example above block-start after is transformed into block-start inline-end. The following demo has been updated.

Need to extend the float property

In summary, if we take all the proposals that have just been detailed in this part, we can propose a global syntax for the float property:

float: none | [<float-x> || <float-y>] || [<float-a> || <float-b>]

with :

<float-y> = top | bottom
<float-x> = left | right | inside | outside
<float-a> = block-start | block-end | inline-start | inline-end | snap-block(<length> [, start | end | near ]?) | snap-inline(<length> [, start | end | near ]?)
<float-b> = before | after

I have made a little demonstrator to show all the possibilities of this proposal with the application of these additional different kinds of floats: http://demos.pagedmedia.org/page-floats/

Multicolumn layout

In multicolumn layouts, the float-reference property float-reference: column can be used. The floated elements will be placed according to the column which contains the float anchor, e.g. the point in the flow where the floated element would have appeared had it not been a float and instead had been an empty inline element with no margins, borders or padding.

It’s still possible to use float-reference: page in multicolumn layouts. In this case, the same element with the same float value will be placed differently according to its float reference.

Column span

The column-span property allows an element to span all columns when the value of the property is all. An element that spans more than one column is called a spanning element. This is useful for titles which break the flow of the columns and span several columns.

Generally, in the tools explored for this article, an integer value is added for specifying how many columns an element should span across. This possibility is not available for now in the current draft of W3C but it’s very useful in combination with float properties for creating layouts such as those used in newspaper formats.

    body {
        column-count: 3
    }
    img {
        column-span: 2
        float-reference: column
        float: top
    }

Clear property

The clear property can be used to prevent stacking of floats. The possible values are the same as the float property, only the snap-block() and snap-inline() values are not available.

The clear property indicates whether an element can be located next to floating elements that precede it (according to the direction indicated by the clear value) or if it needs to be moved in the next float reference container.

With the code that follows, a figure can’t have another figure below it the same page. If another figure has its float anchor in the same page, this figure will appear in the next page when rendering.

figure {
  float-refrence: page;
  float: bottom left;
  clear: bottom;
}

float-defer property

With the float-defer property, a floated element can be deferred to a subsequent fragmentation container. This property works with an integer value or with the keyword last: “This property specifies whether the initial float reference of a page float is the fragmentation container in which the float anchor is placed after previous page floats have been placed, or in another one.” (W3C specifications)

An “n” positive integer value indicates that the element is deferring to the Nth fragmentation container of the “fragmentation flow” after the float anchor is initially placed (after all previous page floats have been placed within the given fragmentation context).

An “n” negative integer value indicates that the element is deferring to the Nth fragmentation container of the “fragmentation flow” counting backward from the end. If the float reference of the deferring element is the page, the count starts on the last page of the flow section of the named page where the initial float anchor appeared. If the float reference of the deferring element is the column, the count starts on the last page column of the page where the initial float anchor appeared.

figure {
  float-reference: page;
  float: top;
  float-defer: 1;
}

figure {
  float-reference: column;
  float: top;
  float-defer: -2;
}

These properties don’t work on any of the tools tested. However, in Prince and Antenna House, the next value is added to the float property: the floated element is placed on the next fragmentation container from its source location.

In conclusion

The large number of values proposed by the W3C Working Draft CSS Page Floats makes it possible, through the combination of properties, to imagine a large number of use cases and therefore to start expressing rich layouts.

The implementation of this specification depends on the tool, but overall they are rather limited.

Browsers haven’t implemented anything.
Prince and Antenna House have their own proprietary values for the float properties, including some that run across those of the W3C specifications.
Vivliostyle have implemented float-reference and float properties very well. Johannes Wilm, the specification’s editor, is a member of the Vivliostyle Project Community
clear and float-defer are yet not implemented anywhere.

The CSS Page Floats specifications and the extensions proposed in this post are good candidates for increasing opportunities for the PagedMedia initiative. This would be interesting not only for the placement figures but also for augmented uses such as the two following examples on which I end this post.

Full page image

figure .full-page {
  height: 8in; /* height of the page */
  float: top;
  float-reference: page;
  position: relative;
  top: -0.8in; /* margin top of the page */
  left: -0.8in; /* left margin of the page */
}

Inserts in margins

.inserts {
  width: 30mm;
  margin-outside: -38mm;
  float-reference: page;
  float: top outside;
}

Build a Table of Contents from your HTML

2020-01-01T14:56:54Z

In this part of the doc, we'll show you how to build a table of contents using a custom script and the css function target-counter() for the content property.

Build the table of contents from your html

In HTML, a table of contents is a <nav> elements that contain a list of the reveleant titles of your document with a link to the unique identifier of each. This part can be done with your own tool/generator but here is an exemple of a script to generate a table of contents in vanilla javascript:

function createToc(config) {
  const content = config.content;
  const tocElement = config.tocElement;
  const titleElements = config.titleElements;

  let tocElementDiv = content.querySelector(tocElement);
  let tocUl = document.createElement("ul");
  tocUl.id = "list-toc-generated";
  tocElementDiv.appendChild(tocUl);

  // add class to all title elements
  let tocElementNbr = 0;
  for (var i = 0; i < titleElements.length; i++) {
    let titleHierarchy = i + 1;
    let titleElement = content.querySelectorAll(titleElements[i]);

    titleElement.forEach(function (element) {
      // add classes to the element
      element.classList.add("title-element");
      element.setAttribute("data-title-level", titleHierarchy);

      // add id if doesn't exist
      tocElementNbr++;
      idElement = element.id;
      if (idElement == "") {
        element.id = "title-element-" + tocElementNbr;
      }
      let newIdElement = element.id;
    });
  }

  // create toc list
  let tocElements = content.querySelectorAll(".title-element");

  for (var i = 0; i < tocElements.length; i++) {
    let tocElement = tocElements[i];

    let tocNewLi = document.createElement("li");

    // Add class for the hierarcy of toc
    tocNewLi.classList.add("toc-element");
    tocNewLi.classList.add(
      "toc-element-level-" + tocElement.dataset.titleLevel
    );

    // Keep class of title elements
    let classTocElement = tocElement.classList;
    for (var n = 0; n < classTocElement.length; n++) {
      if (classTocElement[n] != "title-element") {
        tocNewLi.classList.add(classTocElement[n]);
      }
    }

    // Create the element
    tocNewLi.innerHTML =
      '<a href="#' + tocElement.id + '">' + tocElement.innerHTML + "</a>";
    tocUl.appendChild(tocNewLi);
  }
}

Copy this script to a .js and link this file to your document.

The table of contents need to be generated before paged.js fragment the content into pages. Therefore, you need to register the handler beforeParsed() and call the table of contents script inside.

Add this code in the head of you html document after the call for paged.js script:

<script>
  class handlers extends Paged.Handler {
    constructor(chunker, polisher, caller) {
      super(chunker, polisher, caller);
    }

    beforeParsed(content) {
      createToc({
        content: content,
        tocElement: "#my-toc-content",
        titleElements: [".mw-content-ltr h2", "h3"],
      });
    }
  }
  Paged.registerHandlers(handlers);
</script>

Configuring the script

tocElement: define the id element where the toc list will be created

titleElements: array of the title element you want in the your table of contents. You can add as many as you want and the elements can be selected like any css, for example: .title-1 or .my-content h1

Generate page numbers

Thanks to the previous script, your content is now structured using id for the heading, and the table of contents we created use hyperlinks to those #id:

<!-- the headings in the text-->
<h1 id="pre-digital_era" class="title-element" data-title-level="h1">
  Pre-digital era
</h1>
<p>Content...</p>
<h1 id="digital_era" class="title-element" data-title-level="h1">
  Digital era
</h1>
<p>Content...</p>

<!-- the table of contents-->
<ul id="toc">
  <li><a href="#pre-digital_era">Pre-digital era</a></li>
  <li><a href="#digital_era">Digital era</a></li>
</ul>

In the CSS, the target-counter property is used within ::before and ::after pseudo-elements, using the content property. It can be translated as: find the counter named page that appears where you find the element we’re targetting with the attribute href:

#toc li a::after {
  content: target-counter(attr(href), page);
  float: right;
}

Add styles to the table of contents

If you need to add counters or leaders to your table of contents generated above, here is an exemple of CSS you can use:

/* set the style for the list numbering to none */
#list-toc-generated {
  list-style: none;
}

#list-toc-generated .toc-element {
  break-inside: avoid;
}

#list-toc-generated .toc-element a::after {
  content: " p. " target-counter(attr(href), page);
  float: right;
}

#list-toc-generated .toc-element-level-1 {
  margin-top: 25px;
  font-weight: bold;
}

#list-toc-generated .toc-element-level-2 {
  margin-left: 25px;
}

/* counters */

#list-toc-generated {
  counter-reset: counterTocLevel1;
}

#list-toc-generated .toc-element-level-1 {
  counter-increment: counterTocLevel1;
  counter-reset: counterTocLevel2;
}

#list-toc-generated .toc-element-level-1::before {
  content: counter(counterTocLevel1) ". ";
  padding-right: 5px;
}

#list-toc-generated .toc-element-level-2 {
  counter-increment: counterTocLevel2;
}

#list-toc-generated .toc-element-level-2::before {
  content: counter(counterTocLevel1) ". " counter(counterTocLevel2) ". ";
  padding-right: 5px;
}

/* hack for leaders */

#list-toc-generated {
  overflow-x: hidden;
}

/* fake leading */
#list-toc-generated .toc-element::after {
  content: ".............................................."
    ".............................................."
    ".............................................." "........";
  float: left;
  width: 0;
  padding-left: 5px;
  letter-spacing: 2px;
}

#list-toc-generated .toc-element {
  display: flex;
}

#list-toc-generated .toc-element a::after {
  position: absolute;
  right: 0;
  background-color: white;
  padding-left: 6px;
}

#list-toc-generated .toc-element a {
  right: 0;
}

And voilà!
All the files (scripts, CSS, HTML exemples) to create a table of contents are available on gitlab: https://gitlab.coko.foundation/pagedjs/experiments/tree/master/table-of-content.

News from paged.js!

Successfully published @pagedjs/paged-page

The benefits of a cssPrint preview

But hey, what is a web-component?

Cascading pages or how I learned to style the content inside the page

A recap

About margins

la preview des pages, avec ou sans paged.js

Les bénéfices d’une prévisualisation cssPrint

Mais au fait, c’est quoi un web-component ?

Pages en cascade, ou comment j’ai appris à styliser le contenu à l’intérieur de la page

Récapitulatif

À propos des marges

Documenting the update of the documentation

En documentant la mise à jour de la documentation

Kickstarting the next iteration of Paged.js

A quick recap of what’s on the road map.

Use web components for reusable page elements

Use CSSOM for CSS parsing and manipulation.

WPT Printing test

Pagedjs.org website updates

A quick look at the other tasks

Split out content fragmentation to its own library

Update the fragmentation method to handle multiple break tokens

Tagged PDF support

Parallel-flows within Paged.js

The unfulfilled promise of CSS regions

And CSS Grid was.

The print as a Trojan horse

The configuration of javascript

What's happening.

One last thing

Flux parallel avec Paged.js

La promesse non tenue des régions CSS

Et CSS Grid fut.

Le print comme cheval de Troie

pagedjs-parallel-flows

La config du javascript

Ce qui se passe.

Bonus, une expérimentation.

Une dernière chose

A new chapter in Paged.js life

Didn’t you skip a number? Where is 1.0?

So long paged.js, hello paged.js neue

Meet the team

On paged.js future

Le prochain chapitre de Paged.js

2.0 ? Mais où est passé la 1.0 ?

Paged.js neue

La nouvelle équipe.

À propos du futur de paged.js

So long @media screen!

I want to go back to have a preview on screen!

Enough with breaking changes, we want features!

You can now have multiple nested named pages:

We have an index for all the tests we have in pagedjs (we call’em specs)

Tables improvement.

There is a new hook in town.

Looping is gone (but being a loop, it may be back)

One but not least

Paged Break, the long overdue update

Goodbye web2print, hello web+print

A collection of starter kits for Paged.js

The spread book template: the lightest starter-kit

The advanced interface template: to facilitate your design process

The “print-a-webpage” template: a responsive web page that can be printed

Don't forget your local server

Uke and inks

Editoria, the Book Production Center

Paged.js: hooks and order

Where the humuhumunukunukuapuaa goes swimming by

Changes in the DOM

Page-float? Are you going to talk about page-float?

The custom property with its custom values

Layout time!

Paged.js 0.2.0 Release notes

Hey yall! We have footnotes!

Release notes

In other places

A paged.js hackathon at EnsadLab

2.0 ? Mais où est passé la 1.0 ?

The `note()` and `element()` functions