diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..0ce5af5 --- /dev/null +++ b/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)/*.* diff --git a/README.md b/README.md index da0ebc7..083270c 100644 --- a/README.md +++ b/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/`. diff --git a/example/example.md b/example/example.md index 6285e98..4983b81 100644 --- a/example/example.md +++ b/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 `
`, 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 diff --git a/heg-iso-690.csl b/static/heg-iso-690.csl similarity index 100% rename from heg-iso-690.csl rename to static/heg-iso-690.csl diff --git a/static/bibliotheque-logo.svg b/static/images/bibliotheque-logo.svg similarity index 100% rename from static/bibliotheque-logo.svg rename to static/images/bibliotheque-logo.svg diff --git a/static/by-sa.svg b/static/images/by-sa.svg similarity index 100% rename from static/by-sa.svg rename to static/images/by-sa.svg diff --git a/interface.css b/static/interface.css similarity index 100% rename from interface.css rename to static/interface.css diff --git a/paged.polyfill.js b/static/paged.polyfill.js similarity index 100% rename from paged.polyfill.js rename to static/paged.polyfill.js diff --git a/reload-in-place.js b/static/reload-in-place.js similarity index 100% rename from reload-in-place.js rename to static/reload-in-place.js diff --git a/style.css b/static/style.css similarity index 93% rename from style.css rename to static/style.css index d4dd193..234f39c 100644 --- a/style.css +++ b/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 { diff --git a/template.html b/static/template.html similarity index 90% rename from template.html rename to static/template.html index 46946b6..abf1ee5 100644 --- a/template.html +++ b/static/template.html @@ -31,9 +31,9 @@ $endfor$ when they are unnecessary. --> $if(noscript)$ $else$ - - - + + + $endif$ $for(header-includes)$ $header-includes$