projet: améliore la structure

- Rassemble les fichiers statiques dans leur dossier.
- Crée un Makefile pour construire l'exemple en HTML et en PDF, et aussi
  pour démarrer un serveur web local et pour faciliter la publication de
  version.
- Mets à jour l'exemple avec les possibilités ajoutées (warning).
- Implémente les modifications apportées dans le CSS des projets où ce
  template est utilisé.
- Documente la construction des fichiers et les commandes du Makefile.

Co-Authored-by: iGor milhit <igor@milhit.ch>

Makefile

@@ -0,0 +1,54 @@
+EXAMPLE_FOLDER := example
+PROJECT_STATIC_FOLDER := static
+EXAMPLE_STATIC_FOLDER := $(EXAMPLE_FOLDER)/static
+RELEASE_FOLDER := release
+
+EXAMPLE_FILENAME := example
+EXAMPLE_BIBLIOGRAPHY_PATH := $(EXAMPLE_FOLDER)/references.bib
+CSL_PATH := $(PROJECT_STATIC_FOLDER)/heg-iso-690.csl
+
+GIT_LAST_TAG := $(shell git describe --tags --abbrev=0 2>/dev/null || echo "no-tag")
+
+.PHONY: all
+all: pdf
+
+.PHONY: serve
+serve:
+	python -m http.server
+
+.PHONY: html
+html:
+	pandoc --to=html --standalone \
+	--template=$(PROJECT_STATIC_FOLDER)/template.html \
+	--css=../$(PROJECT_STATIC_FOLDER)/style.css \
+	-V static='../static' \
+	--toc --toc-depth=2 \
+	--citeproc --bibliography=$(EXAMPLE_BIBLIOGRAPHY_PATH) --csl=$(CSL_PATH) \
+	--out=$(EXAMPLE_FOLDER)/$(EXAMPLE_FILENAME).html \
+	$(EXAMPLE_FOLDER)/$(EXAMPLE_FILENAME).md
+
+.PHONY: pdf 
+pdf:
+	cd $(EXAMPLE_FOLDER); \
+	pandoc --to=pdf --pdf-engine=pagedjs-cli --embed-resource \
+	--template=../$(PROJECT_STATIC_FOLDER)/template.html \
+	--css=../$(PROJECT_STATIC_FOLDER)/style.css \
+	-V static='../static' -V noscript=true \
+	--toc --toc-depth=2 \
+	--citeproc --csl=../$(CSL_PATH) \
+	--out=$(EXAMPLE_FILENAME).pdf \
+	$(EXAMPLE_FILENAME).md
+
+.PHONY: watch
+watch:
+	watchexec -r -w . -i $(EXAMPLE_FOLDER)/$(EXAMPLE_FILENAME).html \
+	-- make html
+
+.PHONY: release
+release:
+	zip -r $(RELEASE_FOLDER)/$(GIT_LAST_TAG).zip static
+	make
+	cp $(EXAMPLE_FOLDER)/$(EXAMPLE_FILENAME).pdf $(RELEASE_FOLDER)/$(GIT_LAST_TAG).pdf
+
+.PHONY: clean
+	rm -f $(RELEASE_FOLDER)/*.*

README.md

@@ -21,24 +21,16 @@ pour générer des PDF à partir d'un contenu en markdown.
 
 ## Usage
 
-Une solution est de télécharger les fichiers et répertoires suivants à la
-racine de votre propre projet :
-
-- `static/`.
-- `style.css`.
-- `template.html`.
-- `interface.css`.
-- `heg-iso-690.csl`.
-
-Vous pouvez faire ces téléchargement à la main, ou télécharger le fichier
-`.zip` de la [publication de version][7].
+Une solution est de télécharger le répertoire `static/` à la racine de votre
+propre projet. Vous pouvez faire ces téléchargement à la main, ou télécharger
+le fichier `.zip` de la [publication de version][7].
 
 Une autre méthode est de cloner le projet et de rédiger votre document au sein
 de celui-ci.
 
 ## Structure du répertoire
 
-À la racine du répertoire se trouve les fichiers nécessaires au modèle :
+Dans le répertoire `static/` se trouvent les fichiers nécessaires au modèle :
 
 - Le modèle lui-même : `template.html`.
 - La feuille de style qui rend possible l'interface web pour la
@@ -48,18 +40,32 @@ de celui-ci.
   car il est la norme utilisée par la charte : `heg-iso-690.csl`. Il est
   extrait du répertoire des styles `.csl` :
   [haute-ecole-de-gestion-de-geneve-iso-690.csl][5].
+- Un fichier javascript avec le *polyfill* du projet `pagedjs`, afin d'éviter
+  de dépendre d'un CDN.
+- Un fichier javascript qui permet de retrouver la bonne place dans la
+  visualisation du HTML servi lorsqu'on recharge la page, pratique en
+  développement.
 
 Dans le dossier `example` se trouvent les sources pour pouvoir donner un
 exemple :
 
 - Le document markdown lui-même : `example.md`.
 - Une liste de références bibliographiques au format BibLaTeX :
-  `references.bib`.
+  `references.bib`, exportées avec l'extension pour Zotero Better BibTeX.
 
-## Prérequis
+## Requis
 
 - `pandoc`.
-- `pagedjc-cli` (`npm install -g puppeteer pagedjs pagedjs-cli`).
+- `pagedjc-cli`.
+- Gnu Make, `watchexec` et python pour utiliser les facilités fournies par le
+  `Makefile`.
+
+## Rédaction du document
+
+Pour la rédaction du document, il est utile de se référer à la documentation de
+la syntaxe markdown, mais aussi à la documentation de `pandoc`. Quelques points
+sont données en exemples dans le fichier `example/example.md`, comme par
+exemple [La police][8] ou [Les titres][9]. 
 
 ## Génération du PDF d'exemple
 
@@ -68,58 +74,64 @@ Lancer les commandes depuis le répertoire `./example`.
 Pour générer le fichier HTML a visualiser dans le navigateur :
 
 ```bash
-pandoc --citeproc \
-       --template=../template.html --css=../style.css \
-       --toc --toc-depth=2 \
-       --to=html --output=example.html example.md
+pandoc \
+  --citeproc --bibliography=references.bib --csl=../static/heg-iso-690.csl \
+  --template=../static/template.html --css=../static/style.css \
+  --toc --toc-depth=2 \
+  -V static=../static
+  --to=html --output=example.html example.md
 ```
 
 - `--citeproc` assure que les références bibliographiques soient traitées.
+- `--bibliography` indique où sont les références.
+- `--csl` précise le style de citation utilisé.
 - `--template=` et `--css=` définissent le modèle et les règles de style à
   utiliser.
 - `--toc` et `toc-depth=2` génèrent la table des matière en se limitant au 2e
   niveau.
+- `-V static=` est une variable permettant d'indiquer dans le fichier HTML le
+  chemin vers le dossier contenant les fichiers statiques. Il faut penser le
+  chemin depuis où le fichier HTML sera servi.
 
 Puis lancer un serveur web à la racine du projet (par exemple avec `python -m
-http.server`), et ouvrir le fichier HTML généré avec Chromium (ou Chrome) pour
+http.server`), et ouvrir le fichier HTML généré avec un navigateur web pour
 pouvoir l'imprimer au format PDF.
 
 Pour générer directement le PDF, en utilisant `pagedjs` au moyen de `pandoc` :
 
 ```bash
-pandoc --citeproc \
-       --to=pdf --pdf-engine=pagedjs-cli \
-       --css=../style.css \
-       --template=../template.html \
-       --toc --toc-depth=2 \
-       -V noscript=true 
-       --output=example.pdf example.md
+pandoc \
+  --citeproc --bibliography=references.bib --csl=../static/heg-iso-690.csl \
+  --to=pdf --pdf-engine=pagedjs-cli \
+  --css=../static/style.css \
+  --template=../static/template.html \
+  --toc --toc-depth=2 \
+  -V noscript=true -V static=../static
+  --output=example.pdf example.md
 ```
 
-- `--pdf-engine=` impose `pagedjs` pour la conversion en PDF.
+- `--pdf-engine=` impose `pagedjs-cli` pour la conversion en PDF.
 - `-V noscript=true` permet d'indiquer que la feuille de style de l'interface
   web de `pagedjs` et les scripts javascript utile dans le navigateur web ne
   soient pas utilisés, car ils perturbent la conversion par `pandoc`.
 
-Pour générer le PDF en utilisant directement `pagedjs` :
+## Commandes (`Makefile`)
 
-```bash
-pandoc --citeproc \
-       --to=html --toc --toc-depth=2 \
-       --template=../template.html --css=../style.css \
-       --output example.html example.md \
-       && pagedjs-cli example.html --style ../style.css --output example.pdf
-```
+Le `Makefile` offre les commandes suivantes :
 
-**Attention !** Chacune de ces méthodes produit des différences. À vous de les
-observer et de choisir laquelle vous convient le mieux.
-
-## Rédaction du document
-
-Pour la rédaction du document, il est utile de se référer à la documentation de
-la syntaxe markdown, mais aussi à la documentation de `pandoc`. Quelques points
-sont données en exemples dans le fichier `example/example.md`, comme par
-exemple [La police][8] ou [Les titres][9]. 
+- `make` ou `make pdf` construit le fichier PDF.
+- `make html` construit le fichier HTML, prêt à être servi.
+- `make watch` reconstruit le fichier HTML à chaque fois qu'un autre fichier
+  est modifié et enregistré.
+- `make serve` utilise python pour démarrer un serveur web local.
+- `make release` :
+  - Crée une archive du répertoire `static/` dans le dossier `release/` et
+    nomme l'archive avec la valeur de la dernière étiquette de l'historique
+    `git`.
+  - Construit le fichier PDF.
+  - Copie le PDF construit dans le dossier `release/` en le nommant avec la
+    même étiquette `git`.
+- `make clean` vide le dossier `release/`.
 
 <!-- références -->
 

example/example.md

@@ -1,6 +1,6 @@
 ---
 title: Un modèle pour la BUNIGE 
-date: Printemps 2023
+date: Automne 2025
 creation_date: 2023-04-21T11:30:49+02:00
 id: 20230421113057
 author:
@@ -10,9 +10,9 @@ logo:
 - ./static/pagedjs-logo.svg
 - ./static/markdown-logo.svg
 lang: fr
-tags: [example, markdown, pagedjs]
+tags: ["example", "markdown", "pagedjs"]
 bibliography: ./references.bib
-csl: ../heg-iso-690.csl
+csl: ../static/heg-iso-690.csl
 link-citations: true
 nocite: |
   @*
@@ -35,7 +35,7 @@ Au terme de cet atelier, vous serez en mesure de :
 [CC BY-SA 4.0][cc-by-sa] --- [Sources][sources]
 :::
 
-[logo]: ../static/by-sa.svg
+[logo]: ../static/images/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
 
@@ -132,13 +132,13 @@ 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*).
+le fichier `/static/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
+## Titres et blocs
 
 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
@@ -166,11 +166,31 @@ titre en question.
 La même chose peut être faite avec des `<div>`, par exemple :
 
 ```markdown
-:::{.class}{#id}
+::: {.class}{#id}
+
 Du texte.
+
 :::
 ```
 
+Ce mécanisme permet d'obtenir des blocs pour mettre en évidence du texte :
+
+```markdown
+::: {.warning}
+
+Texte en évidence.
+
+:::
+```
+
+Ce qui donne :
+
+::: {.warning}
+
+Texte en évidence.
+
+:::
+
 ## Citation
 
 > Tout d’abord un bon éditeur est un éditeur avec coloration syntaxique. Avec

static/style.css

@@ -28,7 +28,7 @@
          * bibliothèque de l'UNIGE. */
         @top-right {
                 content: "";
-                background-image: url("static/bibliotheque-logo.svg");
+                background-image: url("images/bibliotheque-logo.svg");
                 background-position: right;
                 background-repeat: no-repeat;
                 background-size: 25%;
@@ -85,7 +85,7 @@
         margin: 2em auto 1em auto;
     }
     .logo img {
-        max-width: 50%;
+        max-width: 25%;
         padding: .5em;
     }
 
@@ -196,6 +196,7 @@
     figure img {
         max-width: 85%;
         margin: 0 auto;
+        max-height: 35vh;
     }
     figcaption {
         text-align: center;
@@ -207,13 +208,28 @@
         content: "Figure " counter(figureNumber) " : ";
     }
 
-    .exercise {
+    .exercise,
+    .warning {
         background-color: #f2f1f1;
         width: 90%;
         margin: 0 auto;
         border: 2px solid #d80669;
         border-radius: .5em;
-        padding: 0 .5em;
+        padding: .5em;
+        display: flex;
+        align-items: center;
+    }
+
+    .exercice > p,
+    .warning > p {
+        margin: 0;
+        padding-left: .5em;
+    }
+
+    .exercice::before,
+    .warning::before {
+        content: "⚠️";
+        font-size: larger;
     }
 
     blockquote {

static/template.html

@@ -31,9 +31,9 @@ $endfor$
      when they are unnecessary. -->
 $if(noscript)$
 $else$
-  <link href="/interface.css" rel="stylesheet" type="text/css" />
-  <script src="/paged.polyfill.js"></script>
-  <script src="/reload-in-place.js"></script>
+  <link href="$static$/interface.css" rel="stylesheet" type="text/css" />
+  <script src="$static$/paged.polyfill.js"></script>
+  <script src="$static$/reload-in-place.js"></script>
 $endif$
 $for(header-includes)$
   $header-includes$