{"id":34715539,"url":"https://github.com/paul-schuhm/kit-presentation-impression-publication","last_synced_at":"2026-04-25T07:33:51.794Z","repository":{"id":324203228,"uuid":"1096332921","full_name":"paul-schuhm/kit-presentation-impression-publication","owner":"paul-schuhm","description":"CLI kit for creating presentation materials (slides first), printing them in multiple formats, and publishing them to an FTP server","archived":false,"fork":false,"pushed_at":"2025-12-17T10:41:10.000Z","size":3513,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T23:28:39.643Z","etag":null,"topics":["markdown","markdown-slides","marp","marp-cli","marpit","marpit-markdown","pandoc","presentation","presentation-slides","printing","publication","separation-technology","supports","technical-writing","toolkit","workflow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paul-schuhm.png","metadata":{"files":{"readme":"README.fr.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T09:17:42.000Z","updated_at":"2025-12-17T10:41:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paul-schuhm/kit-presentation-impression-publication","commit_stats":null,"previous_names":["paul-schuhm/kit-presentation-impression-publication"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paul-schuhm/kit-presentation-impression-publication","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fkit-presentation-impression-publication","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fkit-presentation-impression-publication/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fkit-presentation-impression-publication/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fkit-presentation-impression-publication/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paul-schuhm","download_url":"https://codeload.github.com/paul-schuhm/kit-presentation-impression-publication/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fkit-presentation-impression-publication/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32254696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T04:23:17.126Z","status":"ssl_error","status_checked_at":"2026-04-25T04:21:53.360Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","markdown-slides","marp","marp-cli","marpit","marpit-markdown","pandoc","presentation","presentation-slides","printing","publication","separation-technology","supports","technical-writing","toolkit","workflow"],"created_at":"2025-12-25T00:56:10.178Z","updated_at":"2026-04-25T07:33:51.789Z","avatar_url":"https://github.com/paul-schuhm.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kit de publication et de diffusion de supports de présentation\n\n- [Kit de publication et de diffusion de supports de présentation](#kit-de-publication-et-de-diffusion-de-supports-de-présentation)\n  - [Design](#design)\n  - [Dépendances](#dépendances)\n  - [Usage (*workflow*)](#usage-workflow)\n    - [Configuration](#configuration)\n    - [Écriture (dev)](#écriture-dev)\n    - [Mise en page](#mise-en-page)\n    - [Publication et diffusion (prod)](#publication-et-diffusion-prod)\n  - [Commentaires](#commentaires)\n  - [Conseils](#conseils)\n  - [Liens utiles](#liens-utiles)\n\nCe kit permet permet de créer des supports de présentation au format Markdown (grâce à Marpit) et de les *imprimer* :\n\n- Au format *HTML slide deck*, pour la présentation *live* ;\n- Au format *HTML Single Page* pour diffuser une version web autonome sur une URL. Idéal pour *diffuser une mise à jour* du support et pour *naviguer* dans le document ;\n- Au format *PDF*, pour diffuser une version fixe et portable ;\n- Au format *epub*.\n\nLe kit permet également d'imprimer des documents markdown standards.\n\nEnfin, le kit permet de publier les différents documents imprimés sur un serveur SFTP.\n\n## Design\n\n- *Simple* ;\n- Respecte la séparation salutaire entre contenu et présentation ;\n- N'est *qu'un script shell* qui encapsule Marp et Pandoc, en ajoutant quelques fonctionnalités utiles pour résoudre de vrais cas d’usage.\n\n\u003cimg src=\"./assets/dfd-print-publish.svg\" width=700\u003e\n\n## Dépendances\n\n- [Marp](https://marp.app/), framework de création de *slides deck* à partir de fichiers Markdown, basé sur [marpit](https://marpit.marp.app/) ;\n- [pandoc](https://pandoc.org/index.html), convertisseur de document universel (par exemple Markdown vers PDF). Très puissant et facile à scripter ;\n- [lftp](https://github.com/lavv17/lftp), client ftp. Peut être remplacé par un autre programme facilement\n\nRendre le script `publish` exécutable :\n\n~~~bash\nchmod +x publish\n~~~\n\n## Usage (*workflow*)\n\n\u003e À adapter, améliorer en fonction des besoins.\n\n### Configuration\n\nVérifier que `marp`, `pandoc` et `lftp` sont bien installés :\n\n~~~bash\nmarp -v\npandoc -v\nlftp -v\n~~~\n\n1. **Dupliquer** le kit de départ (Recommandé : automatiser cette tâche avec un script);\n2. **Créer** un fichier `.env` pour y renseigner la liste des sources à imprimer et vos *credentials* FTP pour publication:\n\n~~~bash\ncp .env.dist .env\n~~~\n\nLister les fichiers à imprimer/publier dans le fichier `.env` :\n\n~~~.env\nSOURCES_SLIDES=(\n    slide-deck.md\n    presentation.md\n)\n\nSOURCES_DOCS=(\n    document.md\n    exercices.md\n)\n~~~\n\n### Écriture (dev)\n\n2. Lancer le *watch* du support sur lequel vous travaillez :\n\n~~~bash\nmarp --html --theme theme.css -w --allow-local-files source.md\n~~~\n\n\u003e Se créer un alias : `alias marpw=\"marp --html --theme theme.css -w --allow-local-files\"` puis `marpw source.md`\n\nOuvrir la version HTML (`source.html`). Dès que le fichier sera édité, le support sera mis à jour (*hot reload*).\n\n3. **Écrire** et développer vos supports au format Markdown ([Markdown Marpit flavor](https://marpit.marp.app/markdown)) ;\n\n### Mise en page\n\nPour la mise en page, utiliser/éditer les fichiers CSS suivants :\n\n- `theme.css` : utilisé par *HTML slide deck* et *PDF*;\n- `style.css` : utiliser par *HTML Single Page* et *epub*\n\n\u003e On pourra facilement surcharger le CSS pour le format *epub* avec [la *media query* `@media print{...}`](https://developer.mozilla.org/fr/docs/Web/CSS/Guides/Media_queries/Using#types_de_m%C3%A9dia) et pour le format *HTML Single Page* avec la *media query* `@media screen{...}` ;\n\n### Publication et diffusion (prod)\n\n4. **Imprimer (et publier)** :\n\n~~~bash\n# Affiche l'aide\n./publish -h\n# Imprime dans tous les formats (par défaut)\n./publish\n# Imprime seulement HTML deck\n./publish.sh --no-html-single --no-pdf --epub --html-deck\n# Ou directement\n./publish.sh --slides-only\n# Imprime seulement HTML deck + PDF :\n./publish.sh --html-deck --pdf --no-html-single --no-epub\n# Imprime seulement epub\n./publish.sh --no-html-single --no-html-deck --no-pdf --epub\n~~~\n\n\u003e Les documents imprimés sont placés par défaut dans le dossier `public/`.\n\nPour **imprimer et publier** sur un serveur ftp :\n\n~~~bash\n# Imprime et Publie sur un serveur ftp  (documents HTML Single Page et PDF par défaut) \n./publish --ftp\n~~~\n\nPour configurer les formats à publier sur le serveur ftp, utiliser les variables d'environnement suivantes :\n\n~~~bash\n#Default values\ndo_publish_html_deck=false\ndo_publish_html_single=true\ndo_publish_pdf=true\ndo_publish_epub=false\n~~~\n\n## Commentaires\n\n- Les slides sont au format [(Marpit) Markdown](https://marpit.marp.app/markdown). Le framework Marpit permet donc de créer des ***slides decks* assez minimalistes**, dans le sens *positif* du terme (*content first* : contenu et hiérarchie claire). **Si vous voulez créer des transitions ou des mises en page sophistiquées, ce n'est peut-être pas l'outil recommandé pour vous** ([même si vous pouvez évidemment le faire avec marp](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md)) ;\n- Les documents publiés **ne contiennent pas les commentaires** placés dans vos sources Markdown. N'hésitez donc pas à vous en servir pour annoter vos sources ;\n- Une table des matières est générée pour le format *HTML Single Page*, afin d'**améliorer la navigabilité** (désactivable, produite par pandoc) ;\n- La procédure pour imprimer au format *HTML Single Page* utilise [un script LUA](./h2-link.lua) pour **générer des ancres pour chaque titre de niveau 2**. Cela permet de **créer et partager des URL vers chaque section du document !**\n- Le document imprimé au format *HTML Single Page* est **autonome** : il contient la feuille de style ainsi que toutes les images. Il peut donc être assez lourd, mais peut être distribué plus facilement ;\n- Marp propose une option pratique pour [mettre une image en background d'une slide](https://marpit.marp.app/image-syntax?id=slide-backgrounds). Ces images ont tendance à casser les formats de document *HTML Single Page* et epub (taille image et caption). Pour cela, une classe `.marp-bg-img` leur est automatiquement ajouté à l'impression. **Utilisez la classe `.marp-bg-img`** dans votre `style.css` pour **styliser** (redimensionner, etc.) **ces images de background** à votre convenance ;\n\n## Conseils\n\n- Adapter les fichiers `style.css` et `theme.css` à vos besoins ;\n- **Le Markdown n'est pas conçu pour la mise en forme**. Aussi, si vous avez besoin de définir des contraintes de dimension sur vos images, des classes ou id, préférer **utiliser directement [le tag HTML `img`](https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/img)** plutôt que la syntaxe Markdown.\n- *Lots of room for improvement !* Il y a encore *beaucoup* de choses à améliorer. Disposer d'*une seule source pour le contenu* que l'on publie vers *différents formats* soulève pas mal de questions intéressantes, fait réfléchir au *design* du système et pose des petites difficultés que l'on peut (apprendre à) résoudre.\n\n## Liens utiles\n\n- [Marp](https://marp.app/), créer ses diapos dans un écosystème full Markdown. Réutiliser ainsi facilement le contenu structuré de vos présentations pour les publier en PDF ou HTML, ou inversement. Basé sur [Marpit](https://marpit.marp.app/),\n- [pandoc](https://pandoc.org/index.html) : convertisseur de document universel\n- [poc Marp](https://github.com/websealevel/poc-marp), un dépôt simple qui sert de référence sur l'usage de Marp\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-schuhm%2Fkit-presentation-impression-publication","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaul-schuhm%2Fkit-presentation-impression-publication","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-schuhm%2Fkit-presentation-impression-publication/lists"}