bunige-pagedjs-template

8.1 KiB

Raw Blame History

title

date

creation_date

author

logo

lang

Objectifs

Au terme de cet atelier, vous serez en mesure de :

Générer un fichier PDF en utilisant le modèle.
Convertir les sources en markdown en HTML afin de l'afficher dans un navigateur web.
Modifier les règles de styles pour adapter le modèle.

:::{#licence}
CC BY-SA 4.0 --- Sources :::

Principes généraux

L'idée de base est de rédiger le contenu du document dans un fichier markdown. Puis d'obtenir un fichier PDF mis en forme selon les modèles utilisé par la bibliothèque de l'UNIGE pour ses formations.

Pour y parvenir, plusieurs méthode sont possibles. Par exemple, le document que vous lisez est rédigé dans le fichier example.md, situé dans le dossier /example/example.md du projet bunige-pagedjs-template. Ce fichier « source » est converti par pandoc au format HTML. Puis, ce fichier est à son tour converti en PDF au moyen de pagedjs.

Il est parfaitement possible de convertir directement le fichier markdown en PDF au moyen de pandoc. Mais cela suppose avoir une distribution LaTeX installée. De plus, pour obtenir un document correspondant à la charte de l'UNIGE, cela demande d'être en mesure de modifier les modèles LaTeX utilisé par pandoc. La section suivante tente d'expliquer en quoi Paged.js facilite cette mise en forme.

Paged.js

Paged.js is a free and open source JavaScript library that paginates content in the browser to create PDF output from any HTML content. This means you can design works for print (eg. books) using HTML and CSS! [@paged.jsPagedJs]

Concrètement, cela permet d'afficher un document HTML dans le navigateur, mais découpé en page comme le serait un document imprimé, par exemple un livre.

Comme il s'agit d'un simple document HTML, il peut être mis en forme au moyen d'une feuille de style CSS, comme pour n'importe quelle page web. Selon ses compétences, on peut préférer mettre en forme un PDF de cette manière, notamment grâce à l'inspecteur du navigateur, permettant de tester directement des modifications.

Pour obtenir un document proche des modèles utilisés par la bibliothèque pour ses documents de formation, les règles ont été placées dans le fichier style.css à la racine du projet.

Écrire le fichier HTML directement permet une grande souplesse. Mais la rédaction d'un texte au format HTML n'est pas spécialement pratique. Pour cela, le format markdown semble préférable. Il suffit de comparer les extraits suivants, d'abord en markdown, puis en HTML :

### Paged.js

> Paged.js is a free and open source JavaScript library that paginates
> content in the browser to create PDF output from any HTML content.
> This means you can design works for print (eg. books) using HTML and
> CSS! [@paged.jsPagedJs]

Concrètement, cela permet d'afficher un document HTML dans le
navigateur, mais découpé en page comme le serait un document
imprimé, par exemple un livre.

![Document paginé dans le navigateur](./static/pagedjs-in-browser.png)

<h3 id="paged.js">Paged.js</h3>
<blockquote>
<p>Paged.js is a free and open source JavaScript library that paginates
content in the browser to create PDF output from any HTML content. This
means you can design works for print (eg. books) using HTML and CSS!
<span class="citation" data-cites="paged.jsPagedJs">
(<a href="#ref-paged.jsPagedJs"
    role="doc-biblioref">Paged.js [sans date]</a>)
</span></p>
</blockquote>
<p>Concrètement, cela permet d’afficher un document HTML dans le
navigateur, mais découpé en page comme le serait un document imprimé,
par exemple un livre.</p>
<figure>
  <img src="./static/pagedjs-in-browser.png"
  alt="Pagination d’un document dans le navigateur à l’aide de Paged.js" />
  <figcaption aria-hidden="true">
    Document paginé dans le navigateur
  </figcaption>
</figure>

Police

Bien que la police TheSans face partie de la charte de l'UNIGE et de la Bibliothèque de l'Université, je trouve qu'elle n'est pas des plus lisible, notamment sur les titres. De plus, la licence de cette police, sauf erreur, n'est pas libre, ce qui en limite l'usage. C'est pourquoi je préfère spécifier ici les polices Noto Sans, Open Sans, Arial, Helvetica, ou la police sans-serif par défaut de votre système ou de votre navigateur.

La police peut être facilement configurable au moyen du sélecteur body dans le fichier style.css (règle déjà existante, dans la section Définitions globales).

Pour les éléments verbatim (pre, code), la police est Lilex, Courier New, Courier, monospace.

Titres

Il y a une particularité avec les titres, qui découlent de l'usage de pandoc. La première et qu'il est possible de définir l'attribut id= des titres avec la syntaxe suivante :

## Titre {#identifiant}

Le template en fait usage pour obtenir l'identifiant first-section pour le premier titre du contenu, celui qui vient immédiatement après les [objectifs]. Ainsi, un sélecteur unique est disponible pour appliquer un saut de page à ce titre, quel que soit son texte. Une logique similaire est appliquée au titre de la bibliographie (bibliography).

De la même façon, une ou plusieurs classes peuvent être attribuées :

## Titre {.class}

Ainsi, on peut ajouter la classe .newpage qui insert un saut de page avant le titre en question.

La même chose peut être faite avec des <div>, par exemple :

:::{.class}{#id}
Du texte.
:::

Citation

Tout d’abord un bon éditeur est un éditeur avec coloration syntaxique. Avec cela, les éléments importants de la syntaxe Markdown, ainsi que les titres, les mots en italique, etc., apparaissent en évidence. Ensuite, un bon éditeur de texte est presque entièrement configurable : il vous sera très bénéfique de configurer selon vos goûts le thème de la coloration syntaxique et de l’interface, ainsi que la police. Cela vous assurera surtout un confort d’écriture. [@masuttiRedigerManipulerDocuments2019]

Tableaux

Voici un exemple de table avec une légende et une numérotation automatique des tableaux, comme c'est le cas pour les images (figures).

ID	Nom	Prénom	Adresse
1	Dupont	Jean	Ch. de la Lune 1
2	Dupond	Pierre	Ch. de la Lune 2
3	Schmidt	Mark	Mondweg 3

Table: Exemple de tableau.

L'exemple suivant est directement copié-collé depuis la documentation officielle de pandoc. Il montre que pandoc permet des extensions de la syntaxe markdown.

Centered Default Right Left Header Aligned Aligned Aligned

First row 12.0 Example of a row that spans multiple lines.

Second row 5.0 Here's another one. Note the blank line between rows.

Table: Here's the caption. It, too, may span multiple lines.

8.1 KiB Raw Blame History Unescape Escape