--- 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](../static/by-sa.svg) \ [CC BY-SA 4.0][cc-by-sa] --- [Sources][sources] ::: [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

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.js [sans date])

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
``` ## Police Pour que la police *TheSans* puisse s'appliquer correctement, elle doit être installée sur votre système d'exploitation. Malheureusement, elle n'est pas publiée avec une licence libre, ce qui en réduit l'usage. Les polices de remplacement sont dans l'ordre *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*). ## 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`). ## 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} [1]: https://git.milhit.ch/igor/bunige-pagedjs-template [2]: https://pandoc.org/MANUAL#extension-multiline_tables