Création de PDF à partir de Markdown avec Pandoc et Latex

Points de base

Cet auteur de l'article Chris Ward explique comment convertir les fichiers de démarrage en PDF à l'aide de Pandoc et de latex pour leur boutique de puces de jeux de plateau open source. Les composants du jeu sont écrits à l'aide de Markdown, et le site Web du jeu est également généré par ces fichiers.

pandoc (un outil de conversion de balisage open source) et le latex (une déclaration de documents et un système de mise en page) sont utilisés pour générer des PDF à partir des fichiers Markdown. Malgré leurs capacités puissantes, ils ne peuvent pas combiner plusieurs PDF sur une seule page, donc Ward utilise l'outil de ligne de commande PDFJAM pour répondre à cette exigence.

L'auteur fournit un guide détaillé sur la façon d'installer les dépendances nécessaires (Markdown, Jekyll, Pandoc, Latex, PDFJAM), et introduit progressivement le processus de construction, y compris la génération de PDF à partir de Markdown, la création de fichiers LaTeX et l'utilisation de PDFJAM pour transférer des cartes de cartes de cartes Combinez sur une page.

Le flux de travail idéal de l'auteur est de générer un fichier PDF tout en générant un site Web, plutôt que lorsque le visiteur le demande. Cette approche permet également à la version de la carte PDF de paraître différente de la page HTML sans utiliser de règles CSS complexes.

Si vous avez lu certains de mes messages sur SitePoint ou ailleurs, vous savez probablement que je travaille sur un jeu de société. Ce jeu, appelé Chip Shop, vous permet de gérer une entreprise informatique dans les années 80 America.

Dans le cadre du projet, j'ai essayé d'ouvrir le jeu entier autant que possible. Après quelques tentatives, j'ai décidé d'utiliser Markdown comme cadre de base pour la plupart des composants de jeu (en particulier les cartes et les instructions).

Étant donné que le site Web du jeu utilise Jekyll, le site Web du jeu est généré à partir du fichier Markdown. Je vais faire une version pré-boîte et auto-imprimée premium du jeu, pour laquelle je dois générer un PDF à partir d'un fichier Markdown.

Target

Mon flux de travail idéal est de générer des fichiers PDF tout en générant le site Web, pas lorsque le visiteur le demande. Cela exclut l'option wkhtmltopdf que j'utilise habituellement pour la génération de PDF, car elle génère du PDF à partir de HTML généré. Une autre raison est que je veux que la version de la carte PDF soit différente de la page HTML, et Jekyll manque de fonctionnalité "Mode de vue" pour y parvenir sans utiliser de règles CSS complexes.

Le fichier de modèle de marque de cartes de la boutique de puces contenant de nombreux champs de pré-information de Markdown pour la mécanique de jeu, tous les champs ne sont pas utilisés sur chaque carte. Pour une impression facile, je dois mettre les cartes sur la page A4 autant que possible - dans ce cas, une grille 3 × 3. En fin de compte, la page doit être imprimée des deux côtés, mais je n'ai pas encore implémenté cela.

pandoc et latex

Toute recherche Web qui génère des solutions PDF à partir de Markdown vous mènera sur le chemin de Pandoc. Pandoc est un outil de conversion de conversion de marque de couteaux de l'armée Swiss Open Source qui prend en charge une grande variété de formats de marque d'entrée et de sortie.

Pour générer des PDF à l'aide de pandoc, le latex est requis. Latex est originaire de la communauté de la recherche scientifique et est un système de déclaration de documents et de disposition. Combiné avec Pandoc et LaTeX, nous pouvons utiliser des variables pour générer des PDF à partir d'une série de fichiers Markdown et de prendre en charge la pré-information de Markdown.

Malgré le puissant Pandoc et le latex, je ne trouve aucun moyen de combiner plusieurs PDF (cartes) sur une seule page, en particulier lorsque vous utilisez des variables dans un fichier de démarrage. Après de nombreuses recherches, j'ai choisi Pdfjam, un simple outil de ligne de commande pour ce besoin.

Installation des dépendances

Markdown

Vous n'avez pas besoin de logiciels de Markdown supplémentaires en plus d'avoir besoin d'un éditeur, il y a beaucoup de rédacteurs en chef et je vous suggère de lire des articles de point de site pour faire votre choix.

Jekyll

Je continuerai à utiliser Jekyll pour illustrer le processus de construction dans les exemples tirés de mon jeu, mais si vous n'avez pas besoin d'un site Web, ce n'est pas une partie nécessaire de la génération de PDF.

pandoc

Sur mon Mac, j'ai installé Pandoc à l'aide de Homebrew, mais tous les systèmes d'exploitation ont des options correspondantes.

latex

Il existe de nombreux mots sur la meilleure façon d'installer le latex, selon vos besoins ou comment vous avez l'intention de l'utiliser. L'installation complète de ses outils et bibliothèques communs peut être proche de 2 Go, mais à la plupart des fins, une installation minimale est suffisante. Lisez la page de téléchargement du projet pour trouver l'option qui vous convient le mieux.

Dans ce tutoriel, nous utiliserons le moteur Xelatex car j'utilise des polices personnalisées. Cependant, vous pouvez choisir n'importe quel moteur qui fournit les fonctionnalités spécifiques dont vous avez besoin.

pdfjam

Selon la façon dont vous installez le latex, vous avez peut-être installé PDFJAM. (Tapez quel pdfjam dans le terminal pour vérifier.) Si vous ne l'avez pas installé, recherchez les détails de l'installation ici.

Processus de construction

Après une certaine considération, j'exécute un script bash en cours d'exécution localement semble être le meilleur choix pour le moment. Il existe un meilleur moyen, mais cela fonctionne, et je peux améliorer le processus plus tard, le transférer dans un système d'intégration continue ou des crochets GIT.

Afficher les scripts bash sur github.

présentons ce script étape par étape maintenant.

Paramètres

bundle install
bundle update

rm -dfr _site
rm -dfr pod

Ces commandes garantissent que les dépendances Ruby requises par Jekyll pour créer un site Web sont à jour, et nous avons supprimé tout site Web et dossiers imprimés existants.

Créez un site Web

jekyll build
mkdir -p pod/pdf/cards

Ensuite, nous construisons le site Web et créons un dossier pour la version imprimée de la carte.

générer du PDF à partir de Markdown

Créons un dossier contenant chaque version PDF du fichier de marque:

for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done

Ce script gère chaque fichier Markdown dans le répertoire _cards, en s'assurant d'observer le champ de pré-information Markdown. En utilisant le modèle Cards.latex (que nous couvrirons plus tard), le moteur en latex correct sort un PDF avec le nom approprié.

Fichier latex

La plupart de la magie de la génération de fichiers de carte à partir de Pandoc se produit dans les modèles de latex.

Afficher les modèles de latex sur github.

Latex est nouveau pour moi, mais ce n'est pas trop compliqué. Je vais expliquer ce que j'ai changé à partir du fichier de latex par défaut (situé dans pandoc_install_dir / data / modèles / default.latex) pour faire fonctionner la carte correctement. Je recommande ShareLatex.com pour les prévisualiser lors de la modification des fichiers de latex.

bundle install
bundle update

rm -dfr _site
rm -dfr pod

Nous avons besoin d'une taille de page spécifique et nous utiliserons les colonnes pour afficher le coût et le score de la carte plus tard. Nous utilisons des graphiques et des polices personnalisées, nous avons donc besoin de ces packages.

Nous essayons de créer une disposition simple claire et concise. Voici comment nous l'implémentons:

jekyll build
mkdir -p pod/pdf/cards

Je pense qu'une grande partie de ce qui précède est assez facile à comprendre pour quiconque est habitué à coder ou à étiqueter. Nous créons des éléments de la carte, en les alignons, en définissant la taille de la police et en vérifiant s'il y a des valeurs, puis en les faisant sortir afin que la carte ne se retrouve pas avec des champs vides.

Nous redimensions l'image à une taille spécifique et la centrons. Les valeurs de coût et de score sont organisées en deux colonnes, définies à l'aide de la commande begin {tabular}, et le nombre de colonnes est défini en utilisant le nombre de l.

combinant des cartes sur une page

Nous utilisons PDFJAM pour créer un grand fichier PDF avec chaque carte PDF individuelle:

for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done

Utilisez cette commande, nous spécifions ce qui suit:

• L'orientation de la page doit toujours être verticale
• Chaque PDF individuel doit être encadré
• Taille de la grille
• suffixe de nom de fichier
• Nom de fichier

pdfjam peut donner une erreur si vous ne publiez pas dans son répertoire de travail, donc je déplace le fichier vers où je le veux réellement (j'espère qu'il sera résolu à l'avenir). Ici, nous pouvons également supprimer un seul fichier PDF si nous n'en avons pas besoin.

c'est tout - nous avons un PDF imprimable de sites Web et de cartes de jeu.

Exécuter le script

J'utilise ./build.sh pour exécuter le script de construction. Puisqu'il y a beaucoup d'images et de traitement PDF, cela prend environ cinq à dix minutes. Ensuite, j'ai un script séparé pour déployer ces dossiers sur le serveur Web.

Étapes suivantes

Ce processus m'a pris un certain temps pour bien faire les choses, mais il est assez bon maintenant pour continuer à améliorer le processus et la mise en page après le test de jeu.

J'espère que vous trouverez mes recherches et mes expériences utiles à votre projet. Si vous avez des commentaires ou des suggestions, faites-le moi savoir.

FAQ (FAQ) sur la création de PDF à partir de Markdown à l'aide de pandoc et de latex

Comment installer pandoc et latex sur mon système?

Pour installer pandoc, vous pouvez l'utiliser à partir du site officiel ( https://www.php.cn/link/8f1dd6e7a88b9cf615c146330c591ba9 .

Puis-je personnaliser l'apparence des PDF créés à l'aide de pandoc et de latex?

Oui, vous pouvez utiliser des modèles de latex pour personnaliser l'apparence du PDF. Pandoc utilise le modèle par défaut pour générer des PDF, mais vous pouvez spécifier vos propres modèles à l'aide de l'option --template. Vous pouvez créer vos propres modèles ou utiliser l'un des nombreux modèles disponibles en ligne, tels que ceux trouvés dans le référentiel GitHub du modèle de latex Wandmalfarbe Pandoc.

Comment convertir les fichiers de démarque en PDF à l'aide de Pandoc et LaTeX?

Pour convertir un fichier Markdown en un PDF, vous pouvez utiliser la commande suivante dans un terminal ou une invite de commande: pandoc yourfile.md -o yourfile.pdf. Remplacez yourfile.md par le nom de votre fichier Markdown et yourfile.pdf par le nom souhaité de votre fichier PDF. Cette commande indique à Pandoc de convertir les fichiers de démarque en PDF en utilisant le modèle de latex par défaut.

(Le reste du contenu FAQ est le même que le texte d'origine, omis ici d'éviter la duplication)

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!