bunige-pagedjs-template/example/example.md

---
title: Un modèle pour la BUNIGE 
date: Printemps 2023
creation_date: 2023-04-21T11:30:49+02:00
id: 20230421113057
author:
- Igor Milhit^[Uni CMU]
- Jane Doe^[Uni MAIL]
logo:
- ./static/pagedjs-logo.svg
- ./static/markdown-logo.svg
lang: fr
tags: [example, markdown, pagedjs]
bibliography: ./references.bib
csl: ../heg-iso-690.csl
link-citations: true
nocite: |
  @*
toc-title: Table des matières
---

## 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}
![Logo de la licence CC BY-SA 4.0][logo] \
[CC BY-SA 4.0][cc-by-sa] --- [Sources][sources]
:::

[logo]: ../static/by-sa.svg
[cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/deed.fr "Texte de la licence en français"
[sources]: https://git.milhit.ch/igor/bunige-pagedjs-template

## Principes généraux {#first-section}

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*][1]. 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.

![Pagination d'un document dans le navigateur à l'aide de Paged.js](./static/pagedjs-in-browser.png)

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 :

```markdown
### 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)
```

```html
<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 :

```markdown
## 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 :

```markdown
## 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 :

```markdown
:::{.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][2] 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.


## Bibliographie {#bibliography}

<!-- références -->

[1]: https://git.milhit.ch/igor/bunige-pagedjs-template
[2]: https://pandoc.org/MANUAL#extension-multiline_tables