Pandoc User's Manual in French - jgm/pandoc GitHub Wiki

Traduit par patrix67

Synopsis

pandoc [options] [input-file]…

Description

Pandoc est une bibliothèque Haskell pour la conversion d'un format de balisage à un autre, et un outil de ligne de commande qui utilise cette bibliothèque.

Pandoc peut convertir entre de nombreux formats de balisage et de traitement de texte, y compris, mais sans s'y limiter, diverses saveurs de Markdown, HTML, LaTeX et Word docx. Pour les listes complètes des formats d'entrée et de sortie, voir les options --from et --to ci-dessous. Pandoc peut aussi produire du PDF en sortie : voir Créer un PDF ci-dessous.

La version améliorée de Markdown de Pandoc comprend la syntaxe pour les tables, les listes de definitions, metadata blocks, notes de bas de page, citations, math, et bien plus encore. Voir ci-dessous sous Pandoc’s Markdown.

Pandoc a une conception modulaire : il se compose d'un ensemble de lecteurs, qui analysent le texte dans un format donné et produisent une représentation native du document (un arbre syntaxique abstrait ou AST), et d'un ensemble d' "auteurs", qui convertissent cette représentation native en un format cible. Ainsi, l'ajout d'un format d'entrée ou de sortie ne nécessite que l'ajout d'un lecteur ou d'un rédacteur. Les utilisateurs peuvent également exécuter des filtres pandoc pour modifier l'AST intermédiaire.

Comme la représentation intermédiaire d'un document de pandoc est moins expressive que de nombreux formats entre lesquels il est converti, il ne faut pas s'attendre à des conversions parfaites entre chaque format et tous les autres. Pandoc tente de préserver les éléments structurels d'un document, mais pas les détails de formatage tels que la taille des marges. Et certains éléments du document, tels que les tableaux complexes, peuvent ne pas correspondre au modèle de document simple de Pandoc. Alors que les conversions de Pandoc's Markdown vers tous les formats aspirent à être parfaites, on peut s'attendre à ce que les conversions de formats plus expressifs que Pandoc's Markdown soient perdues.

Utiliser pandoc

Si on ne spécifie pas de fichiers en entrée, l'entrée est lue sur stdin. La sortie par défaut est stdout. Pour envoyer la sortie vers un fichier, utiliser l'option -o :

pandoc -o output.html input.txt

Par défaut, pandoc produit un fragment de document. Pour produire un document autonome (par exemple un fichier HTML valide comprenant <head> et <body>), utiliser l'option -s ou --standalone :

pandoc -s -o output.html input.txt

Pour plus d'informations sur la manière dont les documents autonomes sont produits, voir Modèles ci-dessous.

Si plusieurs fichiers d'entrée sont donnés, pandoc les concaténera tous (avec des lignes blanches entre eux) avant de les analyser (utiliser --file-scope pour analyser les dossiers individuellement).

Spécification de formats

Le format de l'entrée et de la sortie peut être spécifié explicitement à l'aide d'options de ligne de commande. Le format d'entrée peut être spécifié à l'aide de l'option -f/--from option, le format de sortie en utilisant l'option -t/--to. Ainsi, pour convertir hello.txt de Markdown à LaTeX, vous pourriez taper :

pandoc -f markdown -t latex hello.txt

Pour convertir hello.htmlde  HTML à Markdown:

pandoc -f html -t markdown hello.html

Les formats d'entrée et de sortie pris en charge sont énumérés dans les options Options (voir -f pour les formats d'entrée et -tpour les  formats en sortie). Vous avez aussi pandoc --list-input-formats et pandoc --list-output-formats pour imprimer les listes des formats pris en charge.

Si le format d'entrée ou de sortie n'est pas spécifié explicitement, pandoc tentera de le deviner à partir des extensions des noms de fichiers. Ainsi, par exemple,

pandoc -o hello.tex hello.txt

convertira hello.txt de Markdown à LaTeX. Si aucun fichier de sortie n'est spécifié (de sorte que la sortie passe à stdout), ou si l'extension du fichier de sortie est inconnue, le format de sortie sera par défaut HTML. Si aucun fichier d'entrée n'est spécifié (de sorte que l'entrée provient de stdin), ou si les extensions des fichiers d'entrée sont inconnues, le format d'entrée sera supposé être Markdown.

Codage des caractères

Pandoc utilise le codage de caractères UTF-8 pour l'entrée et la sortie. Si votre codage de caractères local n'est pas UTF-8, vous devez faire passer l'entrée et la sortie par iconv:

iconv -t utf-8 input.txt | pandoc | iconv -f utf-8

Notez que dans certains formats de sortie (tels que HTML, LaTeX, ConTeXt, RTF, OPML, DocBook et Texinfo), l'information sur le codage des caractères est incluse dans l'en-tête du document, qui ne sera inclus que si vous utilisez l'option -s/--standalone.

Créer un PDF

Pour produire un PDF, il faut spécifier un fichier de sortie avec une extension .pdf :

pandoc test.txt -o test.pdf

Par défaut, pandoc utilisera LaTeX pour créer le PDF, ce qui nécessite l'installation d'un moteur LaTeX (voir --pdf-engineci-dessous). Sinon, pandoc peut utiliser ConTeXt, roff ms ou HTML comme format intermédiaire. Pour ce faire, il faut spécifier un fichier de sortie avec une extension .pdf, comme avant, mais ajouter l'option --pdf-engine ou -t context, -t html, ou -t msà la ligne de commande. L'outil utilisé pour générer le PDF à partir du format intermédiaire peut être spécifié en utilisant --pdf-engine.

Vous pouvez contrôler le style PDF à l'aide de variables, en fonction du format intermédiaire utilisé : voir variables pour LaTeX, variables for ConTeXt, variables for wkhtmltopdf, variables for ms. Lorsque le HTML est utilisé comme format intermédiaire, la sortie peut être stylée en utilisant --css.

Pour déboguer la création du PDF, il peut être utile d'examiner la représentation intermédiaire : au lieu de -o test.pdf, utilisez par exemple -s -o test.tex pour exporter en LaTeX. Vous pouvez ensuite lancer la commande pdflatex test.tex.

Lorsque vous utilisez LaTeX, les paquets suivants doivent être disponibles (ils sont inclus dans toutes les versions récentes de TeX Live): amsfonts, amsmath, lm, unicode-math, ifxetex, ifluatex, listings (si l'option --listings est utilisée), fancyvrb, longtable, booktabs, graphicx (si le document contient des images), hyperref, xcolor, ulem, geometry (avec la variable geometry positionnée), setspace (avec linestretch), et babel (avec lang). L'usage de xelatex ou de lualatex comme moteur PDF nécessite fontspec. xelatexutilise polyglossia (avec lang), xecjk, et bidi (avec la variabledir positionnée). Si la variable mathspecest positionnée, xelatex utilisera mathspec au lieu de unicode-math. Les paquages upquoteet microtype sont utilisés si disponibles, et csquotes sera utilisé pour la typographie si la variablecsquotesou le champ metadata est positionné à Vrai. Les paquages natbib, biblatex, bibtex, et biber peuvent être utilisés en option pour le rendu des citations. Les paquets suivants seront utilisés pour améliorer la qualité de la production s'ils sont présents, mais pandoc n'exige pas leur présence : upquote (pour des citations directes dans des environnements verbatim), microtype (pour de meilleurs ajustements d'espacement), parskip (pour de meilleurs espaces interparagraphe), xurl (pour de meilleurs sauts de ligne dans les URL), bookmark (pour de meilleurs signets PDF), et footnotehyper ou footnote (pour permettre les notes de bas de page dans les tableaux).

Lecture sur Internet

Au lieu d'un fichier d'entrée, un URI absolu peut être donné. Dans ce cas, pandoc ira chercher le contenu en utilisant HTTP :

pandoc -f html -t markdown https://www.fsf.org

Il est possible de fournir une chaîne User-Agent personnalisée ou un autre en-tête lorsque l'on demande un document à partir d'une URL :

pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
  https://www.fsf.org

Options

Options générales

-f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
Specify input format. FORMAT can be:

Les extensions peuvent être activées ou désactivées individuellement en annexant +EXTENSION ou -EXTENSION au nom du format. Voir ci-dessous Extensions, pour une liste des extensions et de leurs noms. Voir --list-input-formats et  --list-extensions, ci-dessous.

-t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
Specify output format. FORMAT can be:

Notez que les sorties odt, docx, epubet,  pdf ne sont pas dirigées vers stdout à moins que vous le forciez avec -o -.

Les extensions peuvent être activées ou désactivées individuellement en ajoutant +EXTENSION ou -EXTENSION au nom de format. Voir Extensions ci-dessous, pour une liste des extensions et de leurs noms. Voir --list-output-formats et  --list-extensionsci-dessous,

-o FILE, --output=FILE
Ecrire la sortie vers FILE au lieu de stdout. Si FILE est -, la sortie sera stdout, même si un format non textuel (docx, odt, epub2, epub3) est spécifié.

--data-dir=DIRECTORY
Indiquez le répertoire de données de l'utilisateur pour rechercher des fichiers de données pandoc. Si cette option n'est pas spécifiée, le répertoire de données utilisateur par défaut sera utilisé. Sur les systèmes *nix et macOS ce sera le sous-répertoire pandoc du répertoire de données XDG (par défaut, $HOME/.local/share, qu'on peut changer en modifiant la variable d'environnement XDG_DATA_HOME. Si ce répertoire n'existe pas, $HOME/.pandoc sera utilisé (compatibilité ascendante). Dans Windows, le répertoire de données de l'utilisateur par défaut est C:\Users\USERNAME\AppData\Roaming\pandoc. Vous pouvez trouver le répertoire des données de l'utilisateur par défaut sur votre système en consultant la sortie de pandoc --version. Un répertoire reference.odt, reference.docx, epub.css, templates, slidy, slideousou,  s5 placé dans ce répertoire remplacera les valeurs par défaut de pandoc.

-d FILE, --defaults=FILE
Indiquez un ensemble de paramètres d'options par défaut. FILE est un fichier YAML dont les champs correspondent aux paramètres d'option de la ligne de commande. Toutes les options de conversion de documents, y compris les fichiers d'entrée et de sortie, peuvent être définies à l'aide d'un fichier par défaut. Le fichier sera d'abord recherché dans le répertoire de travail, puis dans le sous-répertoire defaults du répertoire des données utilisateur (voir --data-dir). L'extension.yaml peut être omise. Voir la section Default files pour plus d'informations sur le format du fichier. Les paramètres du fichier par défaut peuvent être écrasés ou étendus par des options ultérieures sur la ligne de commande.

--bash-completion
Generate a bash completion script. To enable bash completion with pandoc, add this to your .bashrc:

eval "$(pandoc --bash-completion)"

--verbose
Donne une sortie de débogage bavarde. Actuellement, cela n'a d'effet qu'avec une sortie PDF.

--quiet
Supprimer les messages d'avertissement.

--fail-if-warnings
Sortir avec le statut d'erreur s'il y a des avertissements.

--log=FILE
Inscrire dans le FICHIER les messages de log au format JSON lisible par la machine. Tous les messages dépassant le niveau DEBUG seront écrits, quels que soient les paramètres de verbosité (--verbose, --quiet).

--list-input-formats
Liste les formats d'entrée pris en charge, un par ligne.

--list-output-formats
Liste les formats de sortie pris en charge, un par ligne.

--list-extensions[=FORMAT]
Liste des extensions prises en charge pour FORMAT, une par ligne, précédée d'un + ou d'un - indiquant si elle est activée par défaut dans FORMAT. Si FORMAT n'est pas spécifié, les valeurs par défaut pour le Markdown de pandoc sont données.

--list-highlight-languages
Liste les langues prises en charge pour la coloration syntaxique, une par ligne.

--list-highlight-styles
Liste les styles pris en charge pour la coloration syntaxique, un par ligne. Voir --highlight-style.

-v, --version
Imprimer la version.

-h, --help
Afficher l'aide.

Options du Lecteur ("Reader")

--shift-heading-level-by=NUMBER
Décalage des niveaux de titres par un nombre entier positif ou négatif. Par exemple, avec --shift-heading-level-by=-1 les rubriques de niveau 2 deviennent des rubriques de niveau 1, et les rubriques de niveau 3 deviennent des rubriques de niveau 2. Les titres ne peuvent pas avoir un niveau inférieur à 1, de sorte qu'un titre qui serait déplacé en dessous du niveau 1 devient un paragraphe ordinaire. Exception : avec un décalage de -N, un titre de niveau N au début du document remplace le titre des métadonnées.  --shift-heading-level-by=-1 is a good choice when converting HTML or Markdown documents that use an initial level-1 heading for the document title and level-2+ headings for sections. --shift-heading-level-by=1 may be a good choice for converting Markdown documents that use level-1 headings for sections to HTML, since pandoc uses a level-1 heading to render the document title.

--base-header-level=NUMBER
Deprecated. Use --shift-heading-level-by=X instead, where X = NUMBER - 1. Specify the base level for headings (defaults to 1).

--strip-empty-paragraphs
Deprecated. Use the +empty_paragraphs extension instead. Ignore paragraphs with no content. This option is useful for converting word processing documents where users have used empty paragraphs to create inter-paragraph space.

--indented-code-classes=CLASSES
Préciser les classes à utiliser pour les blocs de code indentés, par exemple, perl,numberLines ou haskell. Des classes multiples peuvent être séparées par des espaces ou des virgules.

--default-image-extension=EXTENSION
Indiquez une extension par défaut à utiliser lorsque les chemins d'images/URL n'ont pas d'extension. Cela vous permet d'utiliser la même source pour les formats qui nécessitent différents types d'images. Actuellement, cette option ne concerne que les lecteurs Markdown et LaTeX.

--file-scope
Analyser chaque fichier individuellement avant de les combiner pour des documents de plusieurs fichiers. Cela permettra aux notes de bas de page des différents fichiers ayant les mêmes identifiants de fonctionner comme prévu. Si cette option est activée, les notes de bas de page et les liens ne fonctionneront pas d'un fichier à l'autre. La lecture de fichiers binaires (docx, odt, epub) implique --file-scope.

-F PROGRAM, --filter=PROGRAM
Spécifier un exécutable à utiliser comme filtre transformant le pandoc AST après que l'entrée soit analysée et avant que la sortie soit écrite. L'exécutable doit lire JSON à partir de stdin et écrire JSON dans stdout. La JSON doit être formatée comme l'entrée et la sortie de la JSON du pandoc. Le nom du format de sortie sera transmis au filtre en tant que premier argument. De ce fait,

pandoc --filter ./caps.py -t latex

est equivalent à

pandoc -t json | ./caps.py latex | pandoc -f json -t latex

Cette dernière forme peut être utile pour le débogage des filtres.

Les filtres peuvent être écrits dans n'importe quelle langue. Text.Pandoc.JSON exporte toJSONFilter pour faciliter l'écriture des filtres dans Haskell. Ceux qui préfèrent écrire des filtres en python peuvent utiliser le module pandocfilters, installable à partir de PyPI. Il existe également des bibliothèques de filtres pandoc dans PHP, perlet,  JavaScript/node.js.

Par ordre de préférence, pandoc cherchera des filtres dans

  1. un chemin complet ou relatif spécifié (exécutable ou non exécutable)

  2. $DATADIR/filters (exécutable ou non exécutable) où $DATADIR est le répertoire des données des utilisateurs (voir  --data-dirci-dessus, ).

  3. $PATH (exécutable uniquement)

Les filtres et les Lua-filtres sont appliqués dans l'ordre indiqué sur la ligne de commande.

-L SCRIPT, --lua-filter=SCRIPT
Transformer le document de manière similaire aux filtres JSON (voir --filter), mais en utilisant le système de filtrage Lua intégré à pandoc. Le script Lua donné devrait renvoyer une liste de filtres Lua qui seront appliqués dans l'ordre. Chaque filtre Lua doit contenir des fonctions de transformation d'éléments indexées par le nom de l'élément AST sur lequel la fonction de filtrage doit être appliquée.

Le module Lua de pandoc fournit des fonctions d'aide pour la création d'éléments. Il est toujours chargé dans l'environnement du script Lua.

Voici un exemple de script Lua pour la macro-expansion :

function expand_hello_world(inline)
  if inline.c == '{{helloworld}}' then
    return pandoc.Emph{ pandoc.Str "Hello, World" }
  else
    return inline
  end
end

return {{Str = expand_hello_world}}

Par ordre de préférence, pandoc cherchera des filtres Lua dans

  1. un chemin complet ou relatif spécifié (exécutable ou non exécutable)

  2. $DATADIR/filters (exécutable ou non exécutable) où  $DATADIR est le répertoire des données des utilisateurs (voir  --data-dirci-dessus, ).

-M KEY[=VAL], --metadata=KEY[:VAL]
Réglez le champ de métadonnées KEY sur la valeur VAL. Une valeur spécifiée sur la ligne de commande remplace une valeur spécifiée dans le document à l'aide de YAML metadata blocks. Les valeurs seront analysées comme des valeurs booléennes ou des chaînes de caractères YAML. Si aucune valeur n'est spécifiée, la valeur sera traitée comme booléenne true. Comme --variable, --metadata entraîne la définition de variables de modèle. Mais contrairement à  --variable, --metadata affecte les métadonnées du document sous-jacent (qui est accessible à partir de filtres et peut être imprimé dans certains formats de sortie) et les valeurs des métadonnées seront échappées lorsqu'elles seront insérées dans le modèle.

--metadata-file=FILE
Lire les meta-données depuis le fichier YAML fourni (ou JSON). Cette option peut être utilisée avec chaque format d'entrée, mais les balises de texte dans le fichier YAML seront toujours analysées en tant que Markdown. En général, l'entrée sera traitée de la même manière que dans YAML metadata blocks. Cette option peut être utilisée de manière répétée pour inclure plusieurs fichiers de métadonnées ; les valeurs des fichiers spécifiés plus tard sur la ligne de commande seront préférées à celles des fichiers précédents. Les valeurs des métadonnées spécifiées à l'intérieur du document, ou en utilisant -M, écrasent les valeurs spécifiées avec cette option.

-p, --preserve-tabs
Conservez les tabulations au lieu de les convertir en espaces. (Par défaut, pandoc convertit les tabulations en espaces avant d'analyser sa saisie). Notez que cela n'affectera que les tabulations dans les portées de code littéral et les blocs de code. Les tabulations dans le texte normal sont toujours traitées comme des espaces.

--tab-stop=NUMBER
Précisez le nombre d'espaces par tabulation (par défaut, 4).

--track-changes=accept|reject|all
Précise ce qu'il faut faire des insertions, suppressions et commentaires produits par la fonction "Suivi des modifications" de MS Word. accept (par défaut), insère toutes les insertions, et ignore toutes les suppressions . reject insère toutes les suppressions et ignore les insertions. Les deux acceptet  reject ignorent les commentaires. all met en place des insertions, des suppressions et des commentaires, enveloppés dans des "span" avec les classes insertion, deletion, comment-start, et comment-end, respectivement. L'auteur et le moment du changement sont inclus. all est utile pour le script : il n'accepte que les modifications d'un certain réviseur, par exemple, ou avant une certaine date. Si un paragraphe est inséré ou supprimé, track-changes=all produces a span with the class paragraph-insertion/paragraph-deletion avant la rupture du paragraphe concerné. Cette option ne concerne que le lecteur docx.

--extract-media=DIR
Extraire les images et autres supports contenus dans le document source ou liés à celui-ci vers le chemin DIR, en le créant si nécessaire, et ajuster les références des images dans le document afin qu'elles pointent vers les fichiers extraits. Si le format source est un conteneur binaire (docx, epub ou odt), le média est extrait du conteneur et les noms de fichiers originaux sont utilisés. Sinon, le support est lu à partir du système de fichiers ou téléchargé, et les nouveaux noms de fichiers sont construits sur la base des hachages SHA1 du contenu.

--abbreviations=FILE
Spécifie un fichier d'abréviations personnalisé, avec des abréviations, une par ligne. Si cette option n'est pas spécifiée, pandoc lira le fichier de données abbreviations du répertoire des données de l'utilisateur ou se rabattre sur une valeur par défaut du système. Pour voir la valeur par défaut du système, utilisez  pandoc --print-default-data-file=abbreviations. La seule utilisation que fait pandoc de cette liste est dans le lecteur Markdown. Les chaînes de caractères se terminant par un point qui se trouvent dans cette liste seront suivies d'un espace insécable, de sorte que le point ne produira pas d'espace de fin de phrase dans des formats comme LaTeX.

Options générales d'écriture

-s, --standalone
Produire une sortie avec un en-tête et un pied de page appropriés (par exemple un fichier HTML, LaTeX, TEI ou RTF autonome, et non un fragment). Cette option est définie automatiquement pour les sorties pdf, epub, epub3, fb2, docxet,  odt. Pour une sortie native, cette option entraîne l'inclusion de métadonnées ; dans le cas contraire, les métadonnées sont supprimées.

--template=FILE|URL
Utiliser le fichier spécifié comme modèle personnalisé pour le document généré. Implique --standalone. Voir Templates, ci-dessous, pour une description de la syntaxe du modèle. Si aucune extension n'est spécifiée, une extension correspondant à l'auteur sera ajoutée, de sorte que --template=special utilise special.htmlpour les exports  HTML. Si le modèle n'est pas trouvé, pandoc le recherchera dans le répertoire templates du répertoire des données utilisateur (voir --data-dir). Si cette option n'est pas utilisée, un modèle par défaut approprié au format de sortie sera utilisé (voir -D/--print-default-template).

-V KEY[=VAL], --variable=KEY[:VAL]
Définir la variable de modèle KEY à la valeur VAL lors du rendu du document en mode autonome. Si aucune VAL n'est spécifiée, la clé recevra la valeur true.

-D FORMAT, --print-default-template=FORMAT
Imprimez le modèle par défaut du système pour un FORMAT de sortie. (Voir -t pour obtenir une liste des FORMATS possibles). Les modèles dans le répertoire des données utilisateur sont ignorés. Cette option peut être utilisée avec -o/--output pour rediriger la sortie vers un fichier, mais -o/--output doit venir avant --print-default-template sur la ligne de commande.

Notez que certains des modèles par défaut utilisent des modèles partiels, par exemple styles.html. Pour imprimer les partiels, utilisez --print-default-data-file: par exemple, --print-default-data-file=templates/styles.html.

--print-default-data-file=FILE
Imprimer un fichier de données par défaut du système. Les fichiers du répertoire des données utilisateur sont ignorés. Cette option peut être utilisée avec -o/--output pour rediriger la sortie vers un fichier, mais -o/--output doit venir avant --print-default-data-file sur la ligne de commande.

--eol=crlf|lf|native
Spécifier manuellement les fins de ligne : crlf (Windows), lf (macOS/Linux/UNIX), ou native (terminaison de ligne appropriée au système d'exploitation sur lequel le pandoc est exécuté). La valeur par défaut est  native.

--dpi=NUMBER
Indiquez la valeur par défaut des ppp (points par pouce) pour la conversion des pixels en pouces/centimètres et vice versa. (Techniquement, le terme correct serait ppi : pixels par pouce.) La valeur par défaut est 96dpi. Lorsque les images contiennent des informations sur les ppp en interne, la valeur encodée est utilisée au lieu de la valeur par défaut spécifiée par cette option.

--wrap=auto|none|preserve
Déterminez comment le texte est encapsulé dans la sortie (le code source, et non la version rendue). Avec auto (valeur par défaut), pandoc tentera de faire correspondre les lignes à la largeur de colonne spécifiée par --columns (default 72). Avec none, pandoc ne mettra pas du tout les lignes à la longueur. Avec preserve, pandoc s'efforcera de préserver la longueur des lignes du document source (c'est-à-dire que lorsqu'il y a des nouvelles lignes non sémantiques dans la source, il y aura également des nouvelles lignes non sémantiques dans la sortie). La mise à la longueur des automatique des lignes ne fonctionne pas actuellement avec la sortie HTML. Pour la sortie ipynb, cette option affecte la mise à la longueur des cellules markdown.

--columns=NUMBER
Précisez la longueur des lignes en caractères. Cela affecte l'habillage du texte dans le code source généré (voir --wrap). Elle affecte également le calcul de la largeur des colonnes pour les tableaux en texte clair (voir Tables ci-dessous).

--toc, --table-of-contents
Inclut une table des matières générée automatiquement (ou, dans le cas de latex, context, docx, odt, opendocument, rst, ou ms une instruction pour en créer une) dans le document de sortie. Cette option n'a d'effet que si,  -s/--standalone est utilisé, et il n'a aucun effet sur les sorties man, docbook4, docbook5, ou jats.

Notez que si vous produisez un PDF via ms, la table des matières apparaîtra au début du document, avant le titre. Si vous préférez qu'elle soit à la fin du document, utilisez l'option --pdf-engine-opt=--no-toc-relocation.

--toc-depth=NUMBER
Précisez le nombre de niveaux de section à inclure dans la table des matières. La valeur par défaut est 3 (ce qui signifie que les rubriques de niveau 1, 2 et 3 figureront dans le sommaire).

--strip-comments
Supprimez les commentaires HTML dans la source Markdown ou Textile, plutôt que de les transmettre à la sortie Markdown, Textile ou HTML sous forme de HTML brut. Cela ne s'applique pas aux commentaires HTML à l'intérieur des blocs HTML bruts lorsque l'extension markdown_in_html_blocks n'est pas positionnée.

--no-highlight
Désactive la mise en évidence syntaxique pour les blocs de code et les alignements, même lorsqu'un attribut de langue est donné.

--highlight-style=STYLE|FILE
Spécifie le style de coloriage à utiliser dans le code source mis en évidence. Les options sont pygments (par défaut), kate, monochrome, breezeDark, espresso, zenburn, haddock, et tango. Pour plus d'informations sur la mise en évidence de la syntaxe dans le cadre de pandoc, voir Syntax highlighting, ci-dessous. Voir aussi --list-highlight-styles.

Au lieu d'un nom STYLE, un fichier JSON avec l'extension .theme peut être fourni. Il sera analysé comme un thème de mise en évidence de la syntaxe KDE et (s'il est valide) utilisé comme style de mise en évidence.

Pour générer la version JSON d'un style existant, utilisez --print-highlight-style.

--print-highlight-style=STYLE|FILE
Imprime une version JSON d'un style de surlignage, qui peut être modifié, sauvegardé avec une extension.theme, et utilisé avec --highlight-style. Cette option peut être utilisée avec -o/--output pour rediriger la sortie vers un fichier, mais -o/--output doit venir avant --print-highlight-style sur la ligne de commande.

--syntax-definition=FILE
Demande à pandoc de charger un fichier de définition de la syntaxe XML KDE, qui sera utilisé pour la mise en évidence syntaxique des blocs de code correctement marqués. Ce fichier peut être utilisé pour ajouter la prise en charge de nouveaux langages ou pour utiliser des définitions syntaxiques modifiées pour des langages existants. Cette option peut être répétée pour ajouter plusieurs définitions syntaxiques.

-H FILE, --include-in-header=FILE|URL
Inclure le contenu de FILE, mot pour mot, à la fin de l'en-tête. Cela peut être utilisé, par exemple, pour inclure des CSS ou des JavaScript spéciaux dans des documents HTML. Cette option peut être utilisée à plusieurs reprises pour inclure plusieurs fichiers dans l'en-tête. Ils seront inclus dans l'ordre indiqué. Cela implique --standalone.

-B FILE, --include-before-body=FILE|URL
Inclure le contenu du DOSSIER, mot pour mot, au début du corps du document (par exemple, après le tag <body> en HTML, ou la commande \begin{document} de LaTeX). Ceci peut être utilisé pour inclure des barres de navigation ou des bannières dans les documents HTML. Cette option peut être utilisée de manière répétée pour inclure plusieurs fichiers. Ils seront inclus dans l'ordre indiqué. Implique --standalone.

-A FILE, --include-after-body=FILE|URL
Inclure le contenu du DOSSIER, mot pour mot, à la fin du corps du document (avant le tag </body> de HTML, ou la commande\end{document}de  LaTeX). Cette option peut être utilisée à plusieurs reprises pour inclure plusieurs fichiers. Ils seront inclus dans l'ordre indiqué. Implique --standalone.

--resource-path=SEARCHPATH
Liste de chemins pour la recherche d'images et d'autres ressources. Les chemins doivent être séparés par : sur les systèmes Linux, UNIX, et macOS, et par ; sur Windows. Si --resource-path n'est pas spécifié, le chemin de ressource par défaut est le répertoire de travail. Notez que, si --resource-path est spécifié, le répertoire de travail doit être explicitement répertorié sinon il ne sera pas recherché. Par exemple : --resource-path=.:test sera recherché dans le répertoire de travail et le sous-répertoire test, dans cet ordre.

--resource-path n'a d'effet que si (a) le format de sortie intègre des images (par exemple, docx, pdf, ou html avec --self-contained) ou (b) il est utilisé conjointement avec--extract-media.

--request-header=NAME:VAL
Définissez l'en-tête de la requête NAME à la valeur VAL lorsque vous effectuez des requêtes HTTP (par exemple, lorsqu'une URL est donnée sur la ligne de commande, ou lorsque les ressources utilisées dans un document doivent être téléchargées). Si vous êtes derrière un proxy, vous devez également définir la variable d'environnement http_proxy vers http://....

Options affectant des exports spécifiques

--self-contained
Produire un fichier HTML autonome sans dépendance externe, en utilisant data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. Implies --standalone. The resulting file should be “self-contained,” in the sense that it needs no external files and no net access to be displayed properly by a browser. This option works only with HTML output formats, including html4, html5, html+lhs, html5+lhs, s5, slidy, slideous, dzslides, and revealjs. Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source file is remote). Elements with the attribute data-external="1" will be left alone; the documents they link to will not be incorporated in the document. Limitation: resources that are loaded dynamically through JavaScript cannot be incorporated; as a result, --self-contained does not work with --mathjax, and some advanced features (e.g. zoom or speaker notes) may not work in an offline “self-contained” reveal.js slide show.

--html-q-tags
Use <q> tags for quotes in HTML.

--ascii
N'utiliser que des caractères ASCII en sortie. Actuellement pris en charge pour les formats XML et HTML (qui utilisent des entités au lieu d'UTF-8 lorsque cette option est sélectionnée), CommonMark, gfm et Markdown (qui utilisent des entités), roff ms (qui utilisent des échappements hexadécimaux) et, dans une mesure limitée, LaTeX (qui utilise des commandes standard pour les caractères accentués lorsque cela est possible). la sortie roff man utilise ASCII par défaut.

--reference-links
Utilisez des liens de type référence, plutôt que des liens en ligne, pour rédiger des notes ou des textes restructurés. Par défaut, des liens en ligne sont utilisés. Le placement des références de liens est affecté par l' option --reference-location.

--reference-location = block|section|document
Précisez si les notes de bas de page (et les références, si reference-links est mis) sont placés à la fin du bloc courant (de niveau supérieur), de la section courante ou du document. La valeur par défaut est document. Actuellement, il ne concerne que l'export en Markdown.

--atx-headers
Utilisez des titres de type ATX dans la sortie de Markdown. La valeur par défaut est d'utiliser des titres de type setext pour les niveaux 1 et 2, puis des titres ATX. (Note : pour des sorties gfm, les rubriques ATX sont toujours utilisées). Cette option affecte également les cellules Markdown dans la sortie ipynb.

--top-level-division=[default|section|chapter|part]
Traitez les titres de haut niveau comme le type de division donné dans les sorties LaTeX, ConTeXt, DocBook et TEI. L'ordre hiérarchique est le suivant : partie, chapitre, puis section ; toutes les rubriques sont décalées de telle sorte que la rubrique de niveau supérieur devienne le type spécifié. Le comportement par défaut consiste à déterminer le meilleur type de division par le biais des heuristiques : à moins que d'autres conditions ne s'appliquent, section est choisie. Lorsque la variable documentclassest report, book, ou memoir (à moins que l'option articlesoit spécifiée), chapter est implicite comme étant le cadre de cette option. Si  beamer est le format de sortie, spécifiez soit chapter ou part fera en sorte que les rubriques de haut niveau deviennent \part{..}, tandis que les rubriques de second niveau restent par défaut.

-N, --number-sections
Numéroter les titres de section en sortie LaTeX, ConTeXt, HTML ou EPUB. Par défaut, les sections ne sont pas numérotées. Les sections avec classe unnumbered ne seront jamais numérotées, même si --number-sections est spécifié.

--number-offset=NUMBER[,NUMBER,…]
Décalage pour les titres de section dans la sortie HTML (ignoré dans les autres formats de sortie). Le premier chiffre est ajouté au numéro de la section pour les titres de premier niveau, le second pour les titres de second niveau, etc. Ainsi, par exemple, si vous voulez que la première rubrique de premier niveau de votre document soit numérotée "6", indiquez --number-offset=5. If your document starts with a level-2 heading which you want to be numbered “1.5”, specify --number-offset=1,4. Offsets are 0 by default. Implies --number-sections.

--listings
Utiliser le paquage listings de LaTeX. Le paquet ne prend pas en charge le codage multi-octets pour le code source. Pour gérer l'UTF-8, vous devez utiliser un modèle personnalisé. Ce problème est entièrement documenté ici : Encoding issue with the listings package.

-i, --incremental
Faites en sorte que les éléments de la liste dans les diaporamas s'affichent progressivement (un par un). Par défaut, les listes s'affichent toutes en même temps.

--slide-level=NUMBER
Précise que les rubriques ayant le niveau spécifié créent des diapositives (pour beamer, s5, slidy, slideous, dzslides). Les titres au-dessus de ce niveau dans la hiérarchie servent à diviser le diaporama en sections ; les titres en dessous de ce niveau créent des sous-titres à l'intérieur d'une diapositive. Notez que le contenu qui n'est pas contenu sous les titres du niveau de la diapositive n'apparaîtra pas dans le diaporama. Par défaut, le niveau de la diapositive est défini en fonction du contenu du document ; voir
Structuring the slide show.

--section-divs
Mettre les sections dans des étiquettes <section> (ou <div> pour html4), and attach identifiers to the enclosing <section> (or <div>) rather than the heading itself. See Heading identifiers, below.

--email-obfuscation=none|javascript|references
Spécifier une méthode pour cacher les liens mailto:dans les documents HTML. nonelaisse les liens mailto: tels quels. javascript les cache en utilisant JavaScript. references les occulte en imprimant leurs lettres sous forme de références de caractères décimaux ou hexadécimaux. Par défaut, none.

--id-prefix=STRING
Spécifiez un préfixe à ajouter à tous les identificateurs et liens internes dans la sortie HTML et DocBook, et aux numéros de note de bas de page dans la sortie Markdown et Haddock. Ceci est utile pour éviter les doublons d'identificateurs lors de la génération de fragments à inclure dans d'autres pages.

-T STRING, --title-prefix=STRING
Spécifiez STRING comme préfixe au début du titre qui apparaît dans l'en-tête HTML (mais pas dans le titre tel qu'il apparaît au début du corps du HTML). Implique --standalone.

-c URL, --css=URL
Lien vers une feuille de style CSS. Cette option peut être utilisée de manière répétée pour inclure plusieurs fichiers. Ils seront inclus dans l'ordre indiqué.
Une feuille de style est nécessaire pour générer l'EPUB. Si aucune feuille de style n'est fournie en utilisant cette option (ou les champs metadata css ou stylesheet), pandoc va chercher un fichier epub.css dans le répertoire des données des utilisateurs (voir --data-dir). If it is not found there, sensible defaults will be used.

--reference-doc=FILE
Utiliser le fichier spécifié comme référence de style dans la production d'un fichier docx ou ODT.

Docx
Pour les meilleurs résultats, le docx de référence doit être une version modifiée d'un fichier docx produit à l'aide de pandoc. Le contenu du docx de référence est ignoré, mais ses feuilles de style et les propriétés du document (y compris les marges, la taille de la page, l'en-tête et le pied de page) sont utilisées dans le nouveau docx. Si aucun docx de référence n'est spécifié sur la ligne de commande, pandoc recherchera un fichierreference.docx dans le répertoire des données des utilisateurs (voir --data-dir). Si ce n'est pas le cas non plus, des valeurs par défaut raisonnables seront utilisées.

Pour produire un fichierreference.docx personnalisé, faites d'abord une copie dureference.docxpar défaut : pandoc -o custom-reference.docx --print-default-data-file reference.docx. Puis ouvrez custom-reference.docxdans  Word, modifiez les styles comme vous le souhaitez, et enregistrez le fichier. Pour de meilleurs résultats, n'apportez pas de modifications à ce fichier, à part celles des styles utilisés par pandoc :

Styles de paragraphes :

  • Normal
  • Body Text
  • First Paragraph
  • Compact
  • Title
  • Subtitle
  • Author
  • Date
  • Abstract
  • Bibliography
  • Heading 1
  • Heading 2
  • Heading 3
  • Heading 4
  • Heading 5
  • Heading 6
  • Heading 7
  • Heading 8
  • Heading 9
  • Block Text
  • Footnote Text
  • Definition Term
  • Definition
  • Caption
  • Table Caption
  • Image Caption
  • Figure
  • Captioned Figure
  • TOC Heading

Styles de caractères :

  • Default Paragraph Font
  • Body Text Char
  • Verbatim Char
  • Footnote Reference
  • Hyperlink

Styles de tableaux :

  • Table

ODT
Pour de meilleurs résultats, le ODT de référence devrait être une version modifiée d'un ODT produit à l'aide de pandoc. Le contenu de l'ODT de référence est ignoré, mais ses feuilles de style sont utilisées dans le nouvel ODT. Si aucun ODT de référence n'est spécifié sur la ligne de commande, pandoc recherchera un fichier reference.odt dans le répertoire des données des utilisateurs (voir --data-dir). Si ce n'est pas le cas non plus, des valeurs par défaut raisonnables seront utilisées.

Pour produire un reference.odtpersonnalisé, obtenir d'abord une copie du fichier reference.odtpar défaut : pandoc -o custom-reference.odt --print-default-data-file reference.odt. Puis ouvrir custom-reference.odt dans LibreOffice, modifier les styles comme vous le souhaitez, et enregistrer le fichier.

PowerPoint
Les modèles inclus dans Microsoft PowerPoint 2013 (avec les extensions .pptx ou .potx) are known to work, as are most templates derived from these.

L'exigence spécifique est que le modèle commence par les quatre indications suivantes :

  1. Title Slide
  2. Title and Content
  3. Section Header
  4. Two Content

Tous les modèles inclus dans une récente version de MS PowerPoint observent ce critère (vous pouvez cliquer sur Layout dans le menu Home pour vérifier).

Vous pouvez aussi modifier le fichier reference.pptxpar défaut : d'abord executer pandoc -o custom-reference.pptx --print-default-data-file reference.pptx, puis modifier custom-reference.pptxdans  MS PowerPoint (pandoc will use the first four layout slides, as mentioned above).

--epub-cover-image=FILE
Use the specified image as the EPUB cover. It is recommended that the image be less than 1000px in width and height. Note that in a Markdown source document you can also specify cover-image in a YAML metadata block (see EPUB Metadata, below).

--epub-metadata=FILE
Look in the specified XML file for metadata for the EPUB. The file should contain a series of Dublin Core elements. For example:

 <dc:rights>Creative Commons</dc:rights>
 <dc:language>es-AR</dc:language>

By default, pandoc will include the following metadata elements: <dc:title> (from the document title), <dc:creator> (from the document authors), <dc:date> (from the document date, which should be in ISO 8601 format), <dc:language> (from the lang variable, or, if is not set, the locale), and <dc:identifier id="BookId"> (a randomly generated UUID). Any of these may be overridden by elements in the metadata file.

Note: if the source document is Markdown, a YAML metadata block in the document can be used instead. See below under EPUB Metadata.

--epub-embed-font=FILE
Embed the specified font in the EPUB. This option can be repeated to embed multiple fonts. Wildcards can also be used: for example, DejaVuSans-*.ttf. However, if you use wildcards on the command line, be sure to escape them or put the whole filename in single quotes, to prevent them from being interpreted by the shell. To use the embedded fonts, you will need to add declarations like the following to your CSS (see --css):

@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: normal;
src:url("DejaVuSans-Regular.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: bold;
src:url("DejaVuSans-Bold.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: normal;
src:url("DejaVuSans-Oblique.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: bold;
src:url("DejaVuSans-BoldOblique.ttf");
}
body { font-family: "DejaVuSans"; }

--epub-chapter-level=NUMBER
Specify the heading level at which to split the EPUB into separate “chapter” files. The default is to split into chapters at level-1 headings. This option only affects the internal composition of the EPUB, not the way chapters and sections are displayed to users. Some readers may be slow if the chapter files are too large, so for large documents with few level-1 headings, one might want to use a chapter level of 2 or 3.

--epub-subdirectory=DIRNAME
Specify the subdirectory in the OCF container that is to hold the EPUB-specific contents. The default is EPUB. To put the EPUB contents in the top level, use an empty string.

--ipynb-output=all|none|best
Determines how ipynb output cells are treated. all means that all of the data formats included in the original are preserved. none means that the contents of data cells are omitted. best causes pandoc to try to pick the richest data block in each output cell that is compatible with the output format. The default is best.

--pdf-engine=PROGRAM
Utilisez le moteur spécifié lorsque vous produisez un fichier PDF. Les valeurs valides sont pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, prince, contextet  pdfroff. Si le moteur n'est pas dans votre PATH, vous pouvez indiquer ici le chemin complet du moteur. Si cette option n'est pas spécifiée, pandoc utilise les valeurs par défaut suivantes en fonction du format de sortie spécifié à l'aide de -t/--to:

  • -t latex ou rien : pdflatex (autres options: xelatex, lualatex, tectonic, latexmk)
  • -t context: context
  • -t html: wkhtmltopdf (autres options : prince, weasyprint)
  • -t ms: pdfroff

--pdf-engine-opt=STRING
Utilisez la chaîne de caractères donnée comme argument de ligne de commande pour le pdf-engine. Par exemple, pour utiliser un répertoire persistant foopour les fichiers auxiliaires de latexmk, utiliser --pdf-engine-opt=-outdir=foo. Notez qu'aucun contrôle des options en double n'est effectué.

Citation rendering

--bibliography=FILE
Mettre le champ bibliographydans les metadonnées du  document à FILE, en dérogeant à toute valeur fixée dans les métadonnées, et traiter les citations en utilisant pandoc-citeproc. (Ceci est équivalent à --metadata bibliography=FILE --filter pandoc-citeproc.) Si --natbib ou --biblatex est également fourni, pandoc-citeproc n'est pas utilisé, ce qui équivaut à --metadata bibliography=FILE. Si vous fournissez cet argument plusieurs fois, chaque FICHIER sera ajouté à la bibliographie.

--csl=FILE
Mettre le champ csl des métadonnées du document à FILE, en supplantant toute valeur fixée dans les métadonnées. (Cela équivaut à --metadata csl=FILE.) Cette option n'est pertinente qu'avec pandoc-citeproc.

--citation-abbreviations=FILE
Mettre le champ citation-abbreviations des metadonnées du document à FILE, en supplantant toute valeur fixée dans les métadonnées. (Cela équivaut à --metadata citation-abbreviations=FILE.) Cette option n'est pertinente qu'avec pandoc-citeproc.

--natbib
Utilise natbib pour les citations dans la production LaTeX. Cette option n'est pas à utiliser avec le filtre pandoc-citeproc ou avec une sortie PDF. Il est destiné à être utilisé pour produire un fichier LaTeX qui peut être traité avec bibtex.

--biblatex
Utiliser biblatexpour les citations dans la sortie Latex. Cette option n'est pas à utiliser avec le filtre pandoc-citeproc ou avec la sortie PDF. Il est destiné à être utilisé pour produire un fichier LaTeX qui peut être traité avec bibtex or biber.

Math rendering in HTML

The default is to render TeX math as far as possible using Unicode characters. Formulas are put inside a span with class="math", so that they may be styled differently from the surrounding text if needed. However, this gives acceptable results only for basic math, usually you will want to use --mathjax or another of the following options.

--mathjax[=URL]
Use MathJax to display embedded TeX math in HTML output. TeX math will be put between \(...\) (for inline math) or \[...\] (for display math) and wrapped in <span> tags with class math. Then the MathJax JavaScript will render it. The URL should point to the MathJax.js load script. If a URL is not provided, a link to the Cloudflare CDN will be inserted.

--mathml
Convert TeX math to MathML (in epub3, docbook4, docbook5, jats, html4 and html5). This is the default in odt output. Note that currently only Firefox and Safari (and select e-book readers) natively support MathML.

--webtex[=URL]
Convert TeX formulas to <img> tags that link to an external script that converts formulas to images. The formula will be URL-encoded and concatenated with the URL provided. For SVG images you can for example use --webtex https://latex.codecogs.com/svg.latex?. If no URL is specified, the CodeCogs URL generating PNGs will be used (https://latex.codecogs.com/png.latex?). Note: the --webtex option will affect Markdown output as well as HTML, which is useful if you’re targeting a version of Markdown without native math support.

--katex[=URL]
Use KaTeX to display embedded TeX math in HTML output. The URL is the base URL for the KaTeX library. That directory should contain a katex.min.js and a katex.min.css file. If a URL is not provided, a link to the KaTeX CDN will be inserted.

--gladtex
Enclose TeX math in <eq> tags in HTML output. The resulting HTML can then be processed by GladTeX to produce images of the typeset formulas and an HTML file with links to these images. So, the procedure is:

pandoc -s --gladtex input.md -o myfile.htex
gladtex -d myfile-images myfile.htex
# produces myfile.html and images in myfile-images

Options for wrapper scripts

--dump-args
Print information about command-line arguments to stdout, then exit. This option is intended primarily for use in wrapper scripts. The first line of output contains the name of the output file specified with the -o option, or - (for stdout) if no output file was specified. The remaining lines contain the command-line arguments, one per line, in the order they appear. These do not include regular pandoc options and their arguments, but do include any options appearing after a -- separator at the end of the line.

--ignore-args
Ignore command-line arguments (for use in wrapper scripts). Regular pandoc options are not ignored. Thus, for example,

pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

is equivalent to

pandoc -o foo.html -s

Exit codes

If pandoc completes successfully, it will return exit code 0. Nonzero exit codes have the following meanings:

Code Error
3 PandocFailOnWarningError
4 PandocAppError
5 PandocTemplateError
6 PandocOptionError
21 PandocUnknownReaderError
22 PandocUnknownWriterError
23 PandocUnsupportedExtensionError
31 PandocEpubSubdirectoryError
43 PandocPDFError
47 PandocPDFProgramNotFoundError
61 PandocHttpError
62 PandocShouldNeverHappenError
63 PandocSomeError
64 PandocParseError
65 PandocParsecError
66 PandocMakePDFError
67 PandocSyntaxMapError
83 PandocFilterError
91 PandocMacroLoop
92 PandocUTF8DecodingError
93 PandocIpynbDecodingError
97 PandocCouldNotFindDataFileError
99 PandocResourceNotFound

Default files

L'option --defaults peut être utilisée pour spécifier un ensemble d'options. Voici un exemple de fichier de valeurs par défaut qui montre tous les champs qui peuvent être utilisés :

from: markdown+emoji
# reader: may be used instead of from:
to: html5
# writer: may be used instead of to:

# leave blank for output to stdout:
output-file:
# leave blank for input from stdin, use [] for no input:
input-files:
- preface.md
- content.md
# or you may use input-file: with a single value

template: letter
standalone: true
self-contained: false

# note that structured variables may be specified:
variables:Il est destiné à être utilisé pour produire un fichier LaTeX qui peut être traité avec
  documentclass: book
  classoption:
    - twosides
    - draft

# metadata values specified here are parsed as literal
# string text, not markdown:
metadata:
  author:
  - Sam Smith
  - Julie Liu
metadata-files:
- boilerplate.yaml
# or you may use metadata-file: with a single value

# Note that these take files, not their contents:
include-before-body: []
include-after-body: []
include-in-header: []
resource-path: ["."]

# filters will be assumed to be Lua filters if they have
# the .lua extension, and json filters otherwise.  But
# the filter type can also be specified explicitly, as shown:
filters:
- pandoc-citeproc
- wordcount.lua
- type: json
  path: foo.lua

file-scope: false

data-dir:

# ERROR, WARNING, or INFO
verbosity: INFO
log-file: log.json

# citeproc, natbib, or biblatex
cite-method: citeproc
# part, chapter, section, or default:
top-level-division: chapter
abbreviations:

pdf-engine: pdflatex
pdf-engine-opts:
- "-shell-escape"
# you may also use pdf-engine-opt: with a single option
# pdf-engine-opt: "-shell-escape"

# auto, preserve, or none
wrap: auto
columns: 78
dpi: 72

extract-media: mediadir

table-of-contents: true
toc-depth: 2
number-sections: false
# a list of offsets at each heading level
number-offset: [0,0,0,0,0,0]
# toc: may also be used instead of table-of-contents:
shift-heading-level-by: 1
section-divs: true
identifier-prefix: foo
title-prefix: ""
strip-empty-paragraphs: true
# lf, crlf, or native
eol: lf
strip-comments: false
indented-code-classes: []
ascii: true
default-image-extension: ".jpg"

# either a style name of a style definition file:
highlight-style: pygments
syntax-definitions:
- c.xml
# or you may use syntax-definition: with a single value
listings: false

reference-doc: myref.docx

# method is plain, webtex, gladtex, mathml, mathjax, katex
# you may specify a url with webtex, mathjax, katex
html-math-method:
  method: mathjax
  url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
# none, references, or javascript
email-obfuscation: javascript

tab-stop: 8
preserve-tabs: true

incremental: false
slide-level: 2

epub-subdirectory: EPUB
epub-metadata: meta.xml
epub-fonts:
- foobar.otf
epub-chapter-level: 1
epub-cover-image: cover.jpg

reference-links: true
# block, section, or document
reference-location: block
atx-headers: false

# accept, reject, or all
track-changes: accept

html-q-tags: false
css:
- site.css

# none, all, or best
ipynb-output: best

# A list of two-element lists
request-headers:
- ["User-Agent", "Mozilla/5.0"]

fail-if-warnings: false
dump-args: false
ignore-args: false
trace: false

Les champs qui sont omis n'auront que leurs valeurs par défaut habituelles. Ainsi, un fichier par défaut peut être aussi simple qu'une ligne :

verbosity: INFO

Les fichiers Default peuvent être placés dans le sous-dossier defaults du répertoire des données d'utilisateur et utilisées à partir de n'importe quel répertoire. Par exemple, on pourrait créer un fichier spécifiant les valeurs par défaut pour l'écriture de lettres, le sauvegarder sous letter.yaml dans le sous-répertoire defaults du répertoire des données de l'utilisateur, puis invoquer ces valeurs par défaut à partir de tout répertoire utilisant pandoc --defaults letter ou pandoc -dletter.

Lorsque plusieurs fichiers default sont utilisés, leur contenu sera combiné.

Notez que, lorsque les arguments de la ligne de commande peuvent être répétés (--metadata-file, --css, --include-in-header, --include-before-body, --include-after-body, --variable, --metadata, --syntax-definition), les valeurs spécifiées sur la ligne de commande se combineront avec les valeurs spécifiées dans le fichier Default, plutôt que de les remplacer.

Modèles

Lorsque l'option -s/--standalone est utilisée, pandoc utilise un modèle pour ajouter les en-têtes et les pieds de page nécessaires à un document autonome. Pour voir le modèle utilisé par défaut, il suffit de taper

pandoc -D *FORMAT*

où FORMAT est le nom du format de sortie. Un modèle personnalisé peut être spécifié à l'aide de l'option --template. Vous pouvez également remplacer les modèles par défaut du système pour un format de sortie donné FORMAT en mettant un fichier templates/default.*FORMAT* dans le répertoire des données des utilisateurs (voir --data-dir, ci-dessus). Exceptions :

  • Pour une sortie odt, personnalisez le modèle default.opendocument.
  • Pour une sortie pdf, personnalisez le modèle ``default.latex(ou le modèle `default.context`, si vous utilisez -t context, ou le modèle `default.ms`, si vous utilisez -t ms, ou le modèle `default.html` si vous utilisez-t html).
  • docx et pptx n'ont pas de modèle (cependant, vous pouvez utiliser--reference-doc pour personnaliser la sortie).

Les modèles contiennent des variables, qui permettent d'inclure des informations arbitraires à n'importe quel moment du fichier. Ils peuvent être définis en ligne de commande à l'aide de l'option -V/--variable. Si une variable n'est pas définie, pandoc cherchera la clé dans les métadonnées du document, qui peuvent être définies en utilisant soit les blocs de métadonnées YAML ou avec l'option-M/--metadata. En outre, certaines variables sont dotées de valeurs par défaut par pandoc. Voir Variables ci-dessous pour une liste des variables utilisées dans les modèles par défaut de pandoc.

Si vous utilisez des modèles personnalisés, vous devrez peut-être les réviser au fur et à mesure de l'évolution de pandoc. Nous vous recommandons de suivre les modifications apportées aux modèles par défaut et de modifier vos modèles personnalisés en conséquence. Une façon simple de procéder consiste à créer une variante ("fork") du dépôt pandoc-templates et fusionner les changements après chaque libération de pandoc.

Syntaxe des modèles

Commentaires

Tout ce qui se trouve entre la séquence $-- et la fin de la ligne sera traitée comme un commentaire et sera omise de la sortie.

Délimiteurs

Pour marquer les variables et les structures de contrôle dans le modèle, soit $…$ soit ${…} peuvent être utilisés comme délimiteurs. Les styles peuvent également être mélangés dans le même modèle, mais les délimiteurs d'ouverture et de fermeture doivent correspondre dans chaque cas. Le premier délimiteur peut être suivi d'un ou plusieurs espaces ou tabulations, qui seront ignorés. Le délimiteur de fermeture peut être suivi d'un ou plusieurs espaces ou tabulations, qui seront ignorés.

Pour inclure littérallement un $ dans le document, écrire $$.

Variables interpolées

Un logement pour une variable interpolée est un nom de variable entouré de délimiteurs correspondants. Les noms de variables doivent commencer par une lettre et peuvent contenir des lettres, des chiffres, _, -, et .. Les mots-clés it, if, else, endif, for, sep, et endfor ne peuvent pas être utilisés comme noms de variables. Exemples :

$foo$
$foo.bar.baz$
$foo_bar.baz-bim$
$ foo $
${foo}
${foo.bar.baz}
${foo_bar.baz-bim}
${ foo }

Les noms de variables avec des points sont utilisés pour obtenir des valeurs de variables structurées. Ainsi, par exemple, employee.salary restituera la valeur du champ salaire salaryde l'objet qui est la valeur du champemployee.

  • Si la valeur de la variable est une valeur simple, elle sera rendue textuellement. (Notez qu'aucun échappement n'est effectué ; l'hypothèse est que le programme appelant échappera les chaînes de caractères de manière appropriée pour le format de sortie).
  • Si la valeur est une liste, les valeurs seront concaténées.
  • If the value is a map, the string true will be rendered.
  • Toute autre valeur sera rendue comme la chaîne vide.

Conditions

Une condition commence par if(variable) (inclus dans les délimiteurs correspondants) et se termine par endif (inclus dans les délimiteurs correspondants). Il peut éventuellement contenir un else (inclus dans les délimiteurs correspondants). La sectionifest utilisée si variablea une valeur non vide, sinon la sectionelseest utilisée (si présente). Exemples :

$if(foo)$bar$endif$

$if(foo)$
  $foo$
$endif$

$if(foo)$
part one
$else$
part two
$endif$

${if(foo)}bar${endif}

${if(foo)}
  ${foo}
${endif}

${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}

The keyword elseif may be used to simplify complex nested conditionals:

$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
ZZZ
$endif$

Boucles for

Une boucle for commence par for(variable) (inclus dans les délimiteurs correspondants) et se termine par endfor(inclus dans les délimiteurs correspondants).

  • Si variable est un tableau, le contenu de la boucle sera évalué à plusieurs reprises, avec variable étant réglé sur chaque valeur du tableau à tour de rôle, et concaténé.
  • If variable is a map, the material inside will be set to the map.
  • Si la valeur de la variable associée n'est pas un tableau ou une carte, une seule itération sera effectuée sur sa valeur.

Exemples :

$for(foo)$$foo$$sep$, $endfor$

$for(foo)$
  - $foo.last$, $foo.first$
$endfor$

${ for(foo.bar) }
  - ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }

$for(mymap)$
$it.name$: $it.office$
$endfor$

Vous pouvez éventuellement spécifier un séparateur entre des valeurs consécutives en utilisant sep  (inclus dans les délimiteurs correspondants). Le contenu entre sep et le endfor est le séparateu .

${ for(foo) }${ foo }${ sep }, ${ endfor }

Au lieu d'utiliser variabledans la boucle , the special anaphoric keyword it may be used.

${ for(foo.bar) }
  - ${ it.last }, ${ it.first }
${ endfor }

Partials

Les parties (sous-modèles stockés dans différents fichiers) peuvent être incluses en utilisant la syntaxe

${ boilerplate() }

Les parties seront recherchées dans le répertoire contenant le modèle principal, et seront supposées avoir la même extension que le modèle principal si elles n'ont pas d'extension explicite. (Si les fichiers partiels ne se trouvent pas ici, ils seront également recherchés dans le sous-répertoire templatesdu répertoire des données de l'utilisateur.)

Partials may optionally be applied to variables using a colon:

${ date:fancy() }

${ articles:bibentry() }

Si articles est un tableau, ceci va itérer sur ses valeurs, en appliquant la partie bibentry() à chacun. Le deuxième exemple ci-dessus est donc équivalent à

${ for(articles) }
${ it:bibentry() }
${ endfor }

Notez que le mot-clé anaphorique it doit être utilisé lors de l'itération sur les parties. Dans les exemples ci-dessus, les parties bibentry devrait contenir it.title (et ainsi de suite) au lieu de articles.title.

Final newlines are omitted from included partials.

Partials may include other partials.

A separator between values of an array may be specified in square brackets, immediately after the variable name or partial:

${months[, ]}$

${articles:bibentry()[; ]$

The separator in this case is literal and (unlike with sep in an explicit for loop) cannot contain interpolated variables or other template directives.

Nesting

Pour vous assurer que le contenu est "imbriqué", c'est-à-dire que les lignes suivantes sont indentées, utilisez la directive ^ :

$item.number$  $^$$item.description$ ($item.price$)

In this example, if item.description has multiple lines, they will all be indented to line up with the first line:

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)

To nest multiple lines to the same level, align them with the ^ directive in the template. For example:

$item.number$  $^$$item.description$ ($item.price$)
               (Available til $item.sellby$.)

will produce

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)
       (Available til March 30, 2020.)

If a variable occurs by itself on a line, preceded by whitespace and not followed by further text or directives on the same line, and the variable’s value contains multiple lines, it will be nested automatically.

Breakable spaces

Normalement, les espaces dans le modèle lui-même (par opposition aux valeurs des variables interpolées) ne sont pas sécables, mais ils peuvent être rendus sécables dans une partie du modèle en utilisant le mot-clé ~ (terminé par un autre ~).

$~$This long line may break if the document is rendered
with a short line length.$~$

Pipes

Un tuyau ("pipe") transforme la valeur d'une variable ou d'une partie de celle-ci. Les tuyaux sont spécifiés à l'aide d'une barre oblique (/) entre le nom de la variable (ou partiel) et le nom du pipe. Exemple :

$for(name)$
$name/uppercase$
$endfor$

$for(metadata/pairs)$
- $it.key$: $it.value$
$endfor$

$employee:name()/uppercase$

Pipes may be chained:

$for(employees/pairs)$
$it.key/alpha/uppercase$. $it.name$
$endfor$

Some pipes take parameters:

|----------------------|------------|
$for(employee)$
$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
$endfor$
|----------------------|------------|

Actuellement, les pipes suivants sont prédéfinis :

  • pairs: Convertit une carte ou un tableau en un tableau de cartes, chacune avec les champs keyet value. Si la valeur initiale était un tableau, key sera l'index du tableau, commençant par 1 .

  • uppercase: Convertit le texte en majuscules.

  • lowercase: Convertit le texte en minuscules.

  • length: Retourne la longueur de la valeur : nombre de caractères pour une valeur textuelle, nombre d'éléments pour une carte ou un tableau.

  • reverse: Inverse une valeur textuelle ou un tableau, et n'a aucun effet sur les autres valeurs.

  • chomp: Removes trailing newlines (and breakable space).

  • nowrap: Disables line wrapping on breakable spaces.

  • alpha: Converts textual values that can be read as an integer into lowercase alphabetic characters a..z (mod 26). This can be used to get lettered enumeration from array indices. To get uppercase letters, chain with uppercase.

  • roman: Converts textual values that can be read as an integer into lowercase roman numerials. This can be used to get lettered enumeration from array indices. To get uppercase roman, chain with uppercase.

  • left n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the left, with an optional left and right border. Has no effect on other values. This can be used to align material in tables. Widths are positive integers indicating the number of characters. Borders are strings inside double quotes; literal " and \ characters must be backslash-escaped.

  • right n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the right, and has no effect on other values.

  • center n "leftborder" "rightborder": Renders a textual value in a block of width n, aligned to the center, and has no effect on other values.

Variables

Variables de métadonnées

title, author, date
permettent d'identifier les aspects fondamentaux du document. Inclus dans les métadonnées PDF par le biais de LaTeX et ConTeXt. Ils peuvent être définis au moyen d'un pandoc title block, qui permet des auteurs multiples, ou par le biais d'un YAML metadata block:

---
author:
- Aristotle
- Peter Abelard
...

Notez que si vous souhaitez simplement définir des métadonnées PDF ou HTML, sans inclure un bloc titre dans le document lui-même, vous pouvez définir les variables title-meta, author-meta, et date-meta. (Par défaut, elles sont définies automatiquement, sur la base title, author, et date.)

subtitle
sous-titre du document, inclus dans les documents HTML, EPUB, LaTeX, ConTeXt et docx

abstract
résumé du document, inclus dans les documents LaTeX, ConTeXt, AsciiDoc et docx

keywords
liste des mots clés à inclure dans les métadonnées HTML, PDF, ODT, pptx, docx et AsciiDoc ; répéter comme pour authorci-dessus, 

subject
sujet du document, inclus dans les métadonnées ODT, PDF, docx et pptx

description
description du document, incluse dans les métadonnées ODT, docx et pptx. Certaines applications les présentent sous forme de la métadonnée Comments.

category
catégorie de document, incluse dans les métadonnées docx et pptx

En outre, toute métadonnée de chaîne de niveau racine, non incluse dans les métadonnées ODT, docx ou pptx, est ajoutée comme propriété personnalisée. Le bloc de métadonnées YAML suivant, par exemple :

---
title:  'This is the title'
subtitle: "This is the subtitle"
author:
- Author One
- Author Two
description: |
    This is a long
    description.

    It consists of two paragraphs
...

inclura title, author et description en tant que propriétés de document standard et subtitle comme une propriété personnalisée lors de la conversion en docx, ODT ou pptx.

Variables linguistiques

lang
identifies the main language of the document using IETF language tags (following the BCP 47 standard), such as en or en-GB. The Language subtag lookup tool can look up or verify these tags. This affects most formats, and controls hyphenation in PDF output when using LaTeX (through babel and polyglossia) or ConTeXt.

Use native pandoc Divs and Spans with the lang attribute to switch the language:

---
lang: en-GB
...

Text in the main document language (British English).

::: {lang=fr-CA}
> Cette citation est écrite en français canadien.
:::

More text in English. ['Zitat auf Deutsch.']{lang=de}

dir
the base script direction, either rtl (right-to-left) or ltr (left-to-right).

For bidirectional documents, native pandoc spans and divs with the dir attribute (value rtl or ltr) can be used to override the base direction in some output formats. This may not always be necessary if the final renderer (e.g. the browser, when generating HTML) supports the Unicode Bidirectional Algorithm.

When using LaTeX for bidirectional documents, only the xelatex engine is fully supported (use --pdf-engine=xelatex).

Variables for HTML math

classoption
when using KaTeX, you can render display math equations flush left using YAML metadata or with -M classoption=fleqn.

Variables for HTML slides

These affect HTML output when producing slide shows with pandoc.

All reveal.js configuration options are available as variables. To turn off boolean flags that default to true in reveal.js, use 0.

revealjs-url
base URL for reveal.js documents (defaults to reveal.js)

s5-url
base URL for S5 documents (defaults to s5/default)

slidy-url
base URL for Slidy documents (defaults to https://www.w3.org/Talks/Tools/Slidy2)

slideous-url
base URL for Slideous documents (defaults to slideous)

title-slide-attributes
additional attributes for the title slide of reveal.js slide shows. See background in reveal.js and beamer for an example.

Variables for Beamer slides

These variables change the appearance of PDF slides using beamer.

aspectratio
slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)

beamerarticle
produce an article from Beamer slides

beameroption
add extra beamer option with \setbeameroption{}

institute
author affiliations: can be a list when there are multiple authors

logo
logo image for slides

navigation
controls navigation symbols (default is empty for no navigation symbols; other valid values are frame, vertical, and horizontal)

section-titles
enables “title pages” for new sections (default is true)

theme, colortheme, fonttheme, innertheme, outertheme
beamer themes

themeoptions
options for LaTeX beamer themes (a list).

titlegraphic
image for title slide

Variables for PowerPoint

These variables control the visual aspects of a slide show that are not easily controlled via templates.

monofont
font to use for code.

Variables pour LaTeX

Pandoc utilise ces variables pour créer un PDF avec un moteur LaTeX.

Mise en page

block-headings
faire des \paragraph et \subparagraph (fourth- and fifth-level headings, or fifth- and sixth-level with book classes) autonome plutôt que de dépendre des autres niveaux ; nécessite un formatage supplémentaire pour distinguer \subsubsection (third- or fourth-level headings). Au lieu d'utiliser cette option, KOMA-Script peut ajuster les rubriques de manière plus approfondie:

---
documentclass: scrartcl
header-includes: |
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\itshape]{paragraph}
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\scshape,
    indent=0pt]{subparagraph}
...

classoption
option for document class, e.g. oneside; repeat for multiple options:

---
classoption:
- twocolumn
- landscape
...

documentclass
document class: usually one of the standard classes, article, book, and report; the KOMA-Script equivalents, scrartcl, scrbook, and scrreprt, which default to smaller margins; or memoir

geometry
option for geometry package, e.g. margin=1in; repeat for multiple options:

---
geometry:
- top=30mm
- left=20mm
- heightrounded
...

hyperrefoptions
option for hyperref package, e.g. linktoc=all; repeat for multiple options:

---
hyperrefoptions:
- linktoc=all
- pdfwindowui
- pdfpagemode=FullScreen
...

indent
uses document class settings for indentation (the default LaTeX template otherwise removes indentation and adds space between paragraphs)

linestretch
adjusts line spacing using the setspace package, e.g. 1.25, 1.5

margin-left, margin-right, margin-top, margin-bottom
sets margins if geometry is not used (otherwise geometry overrides these)

pagestyle
control \pagestyle{}: the default article class supports plain (default), empty (no running heads or page numbers), and headings (section titles in running heads)

papersize
paper size, e.g. letter, a4

secnumdepth
numbering depth for sections (with --number-sections option or numbersections variable)

Fonts

fontenc
allows font encoding to be specified through fontenc package (with pdflatex); default is T1 (see LaTeX font encodings guide)

fontfamily
font package for use with pdflatex: TeX Live includes many options, documented in the LaTeX Font Catalogue. The default is Latin Modern.

fontfamilyoptions
options for package used as fontfamily; repeat for multiple options. For example, to use the Libertine font with proportional lowercase (old-style) figures through the libertinus package:

---
fontfamily: libertinus
fontfamilyoptions:
- osf
- p
...

fontsize
font size for body text. The standard classes allow 10pt, 11pt, and 12pt. To use another size, set documentclass to one of the KOMA-Script classes, such as scrartcl or scrbook.

mainfont, sansfont, monofont, mathfont, CJKmainfont
font families for use with xelatex or lualatex: take the name of any system font, using the fontspec package. CJKmainfont uses the xecjk package.

mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions, CJKoptions
options to use with mainfont, sansfont, monofont, mathfont, CJKmainfont in xelatex and lualatex. Allow for any choices available through fontspec; repeat for multiple options. For example, to use the TeX Gyre version of Palatino with lowercase figures:

---
mainfont: TeX Gyre Pagella
mainfontoptions:
- Numbers=Lowercase
- Numbers=Proportional
...

microtypeoptions
options to pass to the microtype package

Links

colorlinks
add color to link text; automatically enabled if any of linkcolor, filecolor, citecolor, urlcolor, or toccolor are set

linkcolor, filecolor, citecolor, urlcolor, toccolor
color for internal links, external links, citation links, linked URLs, and links in table of contents, respectively: uses options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists

links-as-notes
causes links to be printed as footnotes

Front matter

lof, lot
include list of figures, list of tables

thanks
contents of acknowledgments footnote after document title

toc
include table of contents (can also be set using --toc/--table-of-contents)

toc-depth
level of section to include in table of contents

BibLaTeX Bibliographies

These variables function when using BibLaTeX for citation rendering.

biblatexoptions
list of options for biblatex

biblio-style
bibliography style, when used with --natbib and --biblatex.

biblio-title
bibliography title, when used with --natbib and --biblatex.

bibliography
bibliography to use for resolving references

natbiboptions
list of options for natbib

Variables for ConTeXt

Pandoc uses these variables when creating a PDF with ConTeXt.

fontsize
font size for body text (e.g. 10pt, 12pt)

headertext, footertext
text to be placed in running header or footer (see ConTeXt Headers and Footers); repeat up to four times for different placement

indenting
controls indentation of paragraphs, e.g. yes,small,next (see ConTeXt Indentation); repeat for multiple options

interlinespace
adjusts line spacing, e.g. 4ex (using setupinterlinespace); repeat for multiple options

layout
options for page margins and text arrangement (see ConTeXt Layout); repeat for multiple options

linkcolor, contrastcolor
color for links outside and inside a page, e.g. red, blue (see ConTeXt Color)

linkstyle
typeface style for links, e.g. normal, bold, slanted, boldslanted, type, cap, small

lof, lot
include list of figures, list of tables

mainfont, sansfont, monofont, mathfont
font families: take the name of any system font (see ConTeXt Font Switching)

margin-left, margin-right, margin-top, margin-bottom
sets margins, if layout is not used (otherwise layout overrides these)

pagenumbering
page number style and location (using setuppagenumbering); repeat for multiple options

papersize
paper size, e.g. letter, A4, landscape (see ConTeXt Paper Setup); repeat for multiple options

pdfa
adds to the preamble the setup necessary to generate PDF/A of the type specified, e.g. 1a:2005, 2a. If no type is specified (i.e. the value is set to True, by e.g. --metadata=pdfa or pdfa: true in a YAML metadata block), 1b:2005 will be used as default, for reasons of backwards compatibility. Using --variable=pdfa without specified value is not supported. To successfully generate PDF/A the required ICC color profiles have to be available and the content and all included files (such as images) have to be standard conforming. The ICC profiles and output intent may be specified using the variables pdfaiccprofile and pdfaintent. See also ConTeXt PDFA for more details.

pdfaiccprofile
when used in conjunction with pdfa, specifies the ICC profile to use in the PDF, e.g. default.cmyk. If left unspecified, sRGB.icc is used as default. May be repeated to include multiple profiles. Note that the profiles have to be available on the system. They can be obtained from ConTeXt ICC Profiles.

pdfaintent
when used in conjunction with pdfa, specifies the output intent for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI) If left unspecified, sRGB IEC61966-2.1 is used as default.

toc
include table of contents (can also be set using --toc/--table-of-contents)

whitespace
spacing between paragraphs, e.g. none, small (using setupwhitespace)

includesource
include all source documents as file attachments in the PDF file

Variables for wkhtmltopdf

Pandoc uses these variables when creating a PDF with wkhtmltopdf. The --css option also affects the output.

footer-html, header-html
add information to the header and footer

margin-left, margin-right, margin-top, margin-bottom
set the page margins

papersize
sets the PDF paper size

Variables for man pages

adjusting
adjusts text to left (l), right (r), center (c), or both (b) margins

footer
footer in man pages

header
header in man pages

hyphenate
if true (the default), hyphenation will be used

section
section number in man pages

Variables for ms

fontfamily
font family (e.g. T or P)

indent
paragraph indent (e.g. 2m)

lineheight
line height (e.g. 12p)

pointsize
point size (e.g. 10p)

Variables set automatically

Pandoc sets these variables automatically in response to options or document contents; users can also modify them. These vary depending on the output format, and include the following:

body
body of document

date-meta
the date variable converted to ISO 8601 YYYY-MM-DD, included in all HTML based formats (dzslides, epub, html, html4, html5, revealjs, s5, slideous, slidy). The recognized formats for date are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy (e.g. Apr. 02, 2018 or April 02, 2018),yyyy[mm[dd]]](e.g.20180402, 201804 or 2018).

header-includes
contents specified by -H/--include-in-header (may have multiple values)

include-before
contents specified by -B/--include-before-body (may have multiple values)

include-after
contents specified by -A/--include-after-body (may have multiple values)

meta-json
JSON representation of all of the document’s metadata. Field values are transformed to the selected output format.

numbersections
non-null value if -N/--number-sections was specified

sourcefile, outputfile
les noms de fichiers source et destination, tels qu'ils sont indiqués sur la ligne de commande. sourcefile peut également être une liste si la saisie provient de plusieurs fichiers, ou vide si la saisie provient de stdin. Vous pouvez utiliser l'extrait suivant dans votre modèle pour les distinguer :

$if(sourcefile)$
$for(sourcefile)$
$sourcefile$
$endfor$
$else$
(stdin)
$endif$

Similarly, outputfile can be - if output goes to the terminal.

If you need absolute paths, use e.g. $curdir$/$sourcefile$.

curdir
working directory from which pandoc is run.

toc
non-null value if --toc/--table-of-contents was specified

toc-title
title of table of contents (works only with EPUB, HTML, opendocument, odt, docx, pptx, beamer, LaTeX)

Extensions

Le comportement de certains lecteurs et "writers" peut être ajusté en activant ou en désactivant diverses extensions.

Une extension peut être activée en ajoutant +EXTENSION au nom du format et désactivé en ajoutant  -EXTENSIONPar exemple, --from markdown_strict+footnotes est du Markdown strict avec les notes de bas de page activées, tandis que --from markdown-footnotes-pipe_tablesest le Markdown de pandoc sans les notes de bas de page, ni les "pipe-tables".

Le lecteur et le créateur Markdown sont de loin ceux qui utilisent le plus les extensions. Les extensions qu'ils utilisent seuls sont donc couvertes dans la section Pandoc’s Markdown ci-dessous  (Voir Markdown variants pour commonmark et gfm.)  Dans ce qui suit, les extensions qui fonctionnent également pour d'autres formats sont couvertes.

Notez que les extensions Markdown ajoutées au format ipynbaffectent les cellules Markdown des notebooks Jupiler (comme les options en ligne de commande telles que --atx-headers).

Typographie

Extension: smart

Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as “Mr.”

Cette extension peut être activée/désactivée pour les formats suivants :

input formats
markdown, commonmark, latex, mediawiki, org, rst, twiki

output formats
markdown, latex, context, rst

enabled by default in
markdown, latex, context (both input and output)

Note: Si vous convertissez en Markdown, alors l' extension smarta l'effet inverse : what would have been curly quotes comes out straight.

In LaTeX, smart means to use the standard TeX ligatures for quotation marks (`` and '' for double quotes, ` and ' for single quotes) and dashes (-- for en-dash and --- for em-dash). If smart is disabled, then in reading LaTeX pandoc will parse these characters literally. In writing LaTeX, enabling smart tells pandoc to use the ligatures when possible; if smart is disabled pandoc will use unicode quotation mark and dash characters.

Headings and sections

Extension: auto_identifiers

Une rubrique sans identifiant explicitement spécifié se verra automatiquement attribuer un identifiant unique basé sur le texte de la rubrique.

Cette extension peut être activée/désactivée pour les formats suivants :

input formats
markdown, latex, rst, mediawiki, textile

output formats
markdown, muse

enabled by default in
markdown, muse

L'algorithme par défaut utilisé pour dériver l'identifiant à partir du texte de l'en-tête est :

  • Supprimer tout formatage, liens, etc..
  • Supprimer toutes les notes de bas de page.
  • Supprimer tous les caractères non alphanumériques, à l'exception des traits de soulignement, des traits d'union et des points.
  • Remplacer tous les espaces et les nouvelles lignes par des traits d'union.
  • Convertir tous les caractères alphabétiques en minuscules.
  • Supprimer tout jusqu'à la première lettre (les identifiants ne peuvent pas commencer par un chiffre ou un signe de ponctuation).
  • S'il ne reste rien après cela, utilisez l'identifiant section.

Thus, for example,

Heading Identifier
Heading identifiers in HTML heading-identifiers-in-html
Maître d'hôtel maître-dhôtel
*Dogs*?--in *my* house? dogs--in-my-house
[HTML], [S5], or [RTF]? html-s5-or-rtf
3. Applications applications
33 section

Ces règles devraient, dans la plupart des cas, permettre de déterminer l'identifiant à partir du texte de l'en-tête. L'exception est lorsque plusieurs rubriques ont le même texte ; dans ce cas, la première obtiendra un identifiant comme décrit ci-dessus ; la seconde obtiendra le même identifiant en y suffixant -1; le troisième avec -2; etc...

(Toutefois, un algorithme différent est utilisé si gfm_auto_identifiers est activée ; voir ci-dessous .)

Ces identificateurs sont utilisés pour fournir des cibles de liens dans la table des matières générée par l'option --toc|--table-of-contents. Ils permettent également de fournir facilement des liens d'une section d'un document à une autre. Un lien vers cette section, par exemple, pourrait ressembler à ceci :

See the section on
[heading identifiers](#heading-identifiers-in-html-latex-and-context).

Notez toutefois que cette méthode de fourniture de liens vers les sections ne fonctionne qu'aux formats HTML, LaTeX et ConTeXt.

Si l'option--section-divsest spécifiée, alors chaque section sera incluse dans une section (ou une div, si html4 a été spécifié), et l'identifiant sera joint comme étiquette de <section> (ou <div>) plutôt que l'en-tête lui-même. Cela permet de manipuler des sections entières à l'aide de JavaScript ou de les traiter différemment en CSS.

Extension: ascii_identifiers

Causes the identifiers produced by auto_identifiers to be pure ASCII. Accents are stripped off of accented Latin letters, and non-Latin letters are omitted.

Extension: gfm_auto_identifiers

Change l'algorithme utilisé par auto_identifiers pour correspondre à la méthode GitHub. Les espaces sont convertis en tirets (-), des caractères majuscules aux caractères minuscules, et des caractères de ponctuation autres que - et _ sont enlevés. Les emojis sont remplacés par leur nom.

Math Input

Les extensions tex_math_dollars, tex_math_single_backslashet,  tex_math_double_backslash sont décrits dans la section consacrée à Markdown Pandoc.

Cependant, ils peuvent également être utilisés avec une entrée HTML. C'est pratique pour lire des pages web formatées avec MathJax, par exemple.

Raw HTML/TeX

The following extensions (especially how they affect Markdown input/output) are also described in more detail in their respective sections of Pandoc’s Markdown.

Extension: raw_html

When converting from HTML, parse elements to raw HTML which are not representable in pandoc’s AST. By default, this is disabled for HTML input.

Extension: raw_tex

Allows raw LaTeX, TeX, and ConTeXt to be included in a document.

This extension can be enabled/disabled for the following formats (in addition to markdown):

input formats
latex, org, textile, html (environments, \ref, and \eqref only), ipynb

output formats
textile, commonmark

Note: as applied to ipynb, raw_html and raw_tex affect not only raw TeX in markdown cells, but data with mime type text/html in output cells. Since the ipynb reader attempts to preserve the richest possible outputs when several options are given, you will get best results if you disable raw_html and raw_tex when converting to formats like docx which don’t allow raw html or tex.

Extension: native_divs

This extension is enabled by default for HTML input. This means that divs are parsed to pandoc native elements. (Alternatively, you can parse them to raw HTML using -f html-native_divs+raw_html.)

When converting HTML to Markdown, for example, you may want to drop all divs and spans:

pandoc -f html-native_divs-native_spans -t markdown

Extension: native_spans

Analogous to native_divs above.

Literate Haskell support

Extension: literate_haskell

Treat the document as literate Haskell source.

This extension can be enabled/disabled for the following formats:

input formats
markdown, rst, latex

output formats
markdown, rst, latex, html

If you append +lhs (or +literate_haskell) to one of the formats above, pandoc will treat the document as literate Haskell source. This means that

  • In Markdown input, “bird track” sections will be parsed as Haskell code rather than block quotations. Text between \begin{code} and \end{code} will also be treated as Haskell code. For ATX-style headings the character ‘=’ will be used instead of ‘#’.

  • In Markdown output, code blocks with classes haskell and literate will be rendered using bird tracks, and block quotations will be indented one space, so they will not be treated as Haskell code. In addition, headings will be rendered setext-style (with underlines) rather than ATX-style (with ‘#’ characters). (This is because ghc treats ‘#’ characters in column 1 as introducing line numbers.)

  • In restructured text input, “bird track” sections will be parsed as Haskell code.

  • In restructured text output, code blocks with class haskell will be rendered using bird tracks.

  • In LaTeX input, text in code environments will be parsed as Haskell code.

  • In LaTeX output, code blocks with class haskell will be rendered inside code environments.

  • In HTML output, code blocks with class haskell will be rendered with class literatehaskell and bird tracks.

Examples:

pandoc -f markdown+lhs -t html

reads literate Haskell source formatted with Markdown conventions and writes ordinary HTML (without bird tracks).

pandoc -f markdown+lhs -t html+lhs

writes HTML with the Haskell code in bird tracks, so it can be copied and pasted as literate Haskell source.

Note that GHC expects the bird tracks in the first column, so indented literate code blocks (e.g. inside an itemized environment) will not be picked up by the Haskell compiler.

Other extensions

Extension: empty_paragraphs

Allows empty paragraphs. By default empty paragraphs are omitted.

This extension can be enabled/disabled for the following formats:

input formats
docx, html

output formats
docx, odt, opendocument, html

Extension: native_numbering

Enables native numbering of figures and tables. Enumeration starts at 1.

This extension can be enabled/disabled for the following formats:

output formats
odt, opendocument

Extension: styles

When converting from docx, read all docx styles as divs (for paragraph styles) and spans (for character styles) regardless of whether pandoc understands the meaning of these styles. This can be used with docx custom styles. Disabled by default.

input formats
docx

Extension: amuse

In the muse input format, this enables Text::Amuse extensions to Emacs Muse markup.

Extension: citations

Some aspects of Pandoc’s Markdown citation syntax are also accepted in org input.

Extension: ntb

In the context output format this enables the use of Natural Tables (TABLE) instead of the default Extreme Tables (xtables). Natural tables allow more fine-grained global customization but come at a performance penalty compared to extreme tables.

Pandoc’s Markdown

Pandoc comprend une version étendue et légèrement révisée de la syntaxe du Markdown de John Gruber. Ce document explique la syntaxe, en notant les différences par rapport au Markdown standard. Sauf indication contraire, ces différences peuvent être supprimées en utilisant le format markdown_strict au lieu de markdown. Des extensions peuvent être activées ou désactivées pour spécifier le comportement de manière plus granulaire. Elles sont décrites ci-après. Voir aussi Extensions ci-dessus, pour les extensions qui fonctionnent également sur d'autres formats.

Philosophie

Markdown est conçu pour être facile à écrire et, plus important encore, facile à lire :

Un document au format Markdown doit pouvoir être publié tel quel, en texte brut, sans avoir l'air d'avoir été marqué avec des balises ou des instructions de formatage. – John Gruber

Ce principe a guidé les décisions de pandoc pour trouver la syntaxe des tableaux, notes de bas de page et autres extensions.

Il y a toutefois un point sur lequel les objectifs de pandoc diffèrent des objectifs initiaux de Markdown. Alors que Markdown a été conçu à l'origine avec la génération HTML à l'esprit, pandoc est conçu pour de multiples formats de sortie. Ainsi, alors que pandoc permet l'intégration de HTML brut, il le décourage et fournit d'autres moyens, non HTML, de représenter les éléments importants d'un document comme les listes de définitions, les tableaux, les mathématiques et les notes de bas de page.

Paragraphes

Un paragraphe est une ou plusieurs lignes de texte suivies d'une ou plusieurs lignes blanches. Les nouvelles lignes sont traitées comme des espaces, de sorte que vous pouvez refondre vos paragraphes comme vous le souhaitez. Si vous avez besoin d'un retour à la ligne, mettez deux espaces ou plus à la fin d'une ligne.

Extension: escaped_line_breaks

Une barre oblique inversée suivie d'une nouvelle ligne est également une rupture de ligne. Remarque : dans les cellules de tableaux à lignes multiples et de grilles, c'est la seule façon de créer un saut de ligne, car les espaces de fin de ligne dans les cellules sont ignorés.

Headings

Il existe deux types de rubriques : Setext et ATX.

Setext-style headings

Un en-tête de type setext est une ligne de texte "soulignée" avec une rangée de signes = (pour un titre de niveau 1) ou de signes - (pour un titre de niveau 2) :

A level-one heading
===================

A level-two heading
-------------------

Le texte de l'en-tête peut contenir un formatage en ligne, tel que l'accentuation (voir Inline formatting, ci-dessous).

ATX-style headings

Une rubrique de type ATX se compose de un à six signes # et une ligne de texte, éventuellement suivie d'un nombre quelconque de signes #. Le nombre de signes # en début de ligne donne le niveau de titre :

## Un titre de niveau 2

### Un titre de niveau 3 ###

Comme pour les titres de type setext, le texte du titre peut contenir un formatage :

# Un titre de niveau 1 avec [lien url](/url) et *emphase*

Extension: blank_before_header

La syntaxe standard de Markdown ne nécessite pas de ligne blanche avant un titre. Pandoc l'exige (sauf, bien sûr, au début du document). La raison de cette exigence est qu'il est trop facile pour un # de se retrouver accidentellement au début d'une ligne (peut-être à cause d'un retour à la ligne). Prenons un exemple :

I like several of their flavors of ice cream:
#22, for example, and #5.

Extension: space_in_atx_header

De nombreuses mises en œuvre de Markdown ne nécessitent pas d'espace entre #ouvrant d'une en-tête ATX et le texte de l'en-tête, de sorte que #5 bolt et #hashtag sont considérés comme des en-têtes. Avec cette extension, pandoc nécessite l'espace.

Heading identifiers

Voir aussi l' extension auto_identifiers ci-dessus.

Extension: header_attributes

Les titres peuvent se voir attribuer des attributs en utilisant cette syntaxe à la fin de la ligne contenant le texte du titre :

{#identifier .class .class key=value key=value}

Ainsi, par exemple, les rubriques suivantes se verront toutes attribuer l'identifiant foo:

# My heading {#foo}

## My heading ##    {#foo}

My other heading   {#foo}
---------------

(Cette syntaxe est compatible avec PHP Markdown Extra.)

Notez que bien que cette syntaxe permette l'attribution de classes et d'attributs de clés/valeurs, les auteurs n'utilisent généralement pas toutes ces informations. Les identificateurs, les classes et les attributs clé/valeur sont utilisés dans les formats HTML et HTML-based tels que EPUB et slidy. Les identificateurs sont utilisés pour les étiquettes et les ancres de liens dans les rédacteurs LaTeX, ConTeXt, Textile, Jira markup et AsciiDoc.

Les titres avec la classe unnumbered ne seront pas numérotés, même si --number-sections est spécifié. Un tiret simple (- ) dans un contexte d'attributs est équivalent à.unnumbered et préférable dans les documents non anglais. Donc,

# My heading {-}

est identique à

# My heading {.unnumbered}

Si la classe unlisted est présente avec unnumbered, le titre ne sera pas inclus dans une table des matières. (Actuellement, cette fonctionnalité n'est mise en œuvre que pour certains formats : ceux basés sur LaTeX et HTML, PowerPoint et RTF).

Extension: implicit_header_references

Pandoc se comporte comme si des liens de référence avaient été définis pour chaque rubrique. Ainsi, pour établir un lien avec une rubrique

# Heading identifiers in HTML

vous pouvez simplement écrire

[Heading identifiers in HTML]

ou

[Heading identifiers in HTML][]

ou

[the section on heading identifiers][heading identifiers in
HTML]

au lieu de donner l'identifiant explicitement :

[Heading identifiers in HTML](#heading-identifiers-in-html)

Si plusieurs rubriques ont un texte identique, la référence correspondante ne sera liée qu'à la première, et vous devrez utiliser des liens explicites pour établir des liens avec les autres, comme décrit ci-dessus.

Comme les liens de référence réguliers, ces références ne sont pas sensibles à la casse.

Les définitions des références de liens explicites ont toujours la priorité sur les références implicites des rubriques. Ainsi, dans l'exemple suivant, le lien pointera vers bar, pas vers #foo:

# Foo

[foo]: bar

Voir [foo]

Citations en bloc

Markdown utilise les conventions du courrier électronique pour citer des blocs de texte. Un bloc de citation est un ou plusieurs paragraphes ou autres éléments de bloc (tels que des listes ou des titres), chaque ligne étant précédée d'un caractère >et d'une espace optionnelle . (Le > doit démarrer à la marge gauche, mais il ne doit pas être indenté de plus de trois espaces.)

> This is a block quote. This
> paragraph has two lines.
>
> 1. This is a list inside a block quote.
> 2. Second item.

Une forme "paresseuse", qui nécessite le caractère >uniquement sur la première ligne de chaque bloc, est également autorisée :

> This is a block quote. This
paragraph has two lines.

> 1. This is a list inside a block quote.
2. Second item.

Parmi les éléments du bloc qui peuvent être contenus dans une citation en bloc, on trouve d'autres citations en bloc. C'est-à-dire que les citations en bloc peuvent être imbriquées :

> This is a block quote.
>
> > A block quote within a block quote.

Si le caractère > est suivi d'un espace facultatif, cet espace sera considéré comme faisant partie du guillemet et non de l'indentation du contenu. Ainsi, pour mettre un bloc de code indenté dans un bloc de guillemets, vous avez besoin de cinq espaces après le >:

>     code

Extension: blank_before_blockquote

La syntaxe standard de Markdown ne nécessite pas de ligne blanche avant une citation bloc. Pandoc l'exige (sauf, bien sûr, au début du document). La raison de cette exigence est qu'il est trop facile pour un > de se retrouver au début d'une ligne par accident (peut-être à cause de l'enroulement de la ligne). Ainsi, à moins que le format markdown_strict soit utilisé, ce qui suit ne produit pas une citation en bloc imbriquée dans pandoc :

> This is a block quote.
>> Nested.

Verbatim (code) blocks

Blocs de code indentés

Un bloc de texte indenté de quatre espaces (ou une tabulation) est traité comme du texte textuel : c'est-à-dire que les caractères spéciaux ne déclenchent pas de formatage particulier, et que tous les espaces et sauts de ligne sont préservés. Par exemple, les caractères spéciaux ne déclenchent pas de formatage spécial et tous les espaces et sauts de ligne sont conservés,

    if (a > 3) {
      moveShip(5 * gravity, DOWN);
    }

L'indentation initiale (quatre espaces ou une tabulation) n'est pas considérée comme faisant partie du texte intégral et est supprimée dans la sortie.

Note : les lignes vierges dans le texte du compte rendu ne doivent pas nécessairement commencer par quatre espaces.

Blocs de code clôturés

Extension: fenced_code_blocks

En plus des blocs de code standard indentés, pandoc prend en charge les blocs de code clôturés. Ceux-ci commencent par une rangée de trois tildes ou plus (~) et se terminent par une rangée de tildes qui doit être au moins aussi longue que la rangée de départ. Tout ce qui se trouve entre ces lignes est traité comme un code. Aucune indentation n'est nécessaire :

~~~~~~~
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~

Comme les blocs de code ordinaires, les blocs de code clôturés doivent être séparés du texte environnant par des lignes blanches.

Si le code lui-même contient une rangée de tildes ou de bâtons "backticks", il suffit d'utiliser une rangée plus longue de tildes ou de bâtons au début et à la fin :

~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~

Extension: backtick_code_blocks

Identique à fenced_code_blocks, mais utilise des "backticks" (`) au lieu de tildes (~).

Extension: fenced_code_attributes

Vous pouvez, si vous le souhaitez, attacher des attributs à un bloc de code clôturé ou à un bloc de code backtick en utilisant cette syntaxe :

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ici mycode est un identificateur, haskell et numberLines sont des classes,  startFrom est un attribut de valeur 100. Certains formats de sortie peuvent utiliser ces informations pour effectuer une mise en évidence syntaxique. Actuellement, les seuls formats de sortie qui utilisent ces informations sont HTML, LaTeX, Docx, Ms et PowerPoint. Si la coloration syntaxique est prise en charge pour votre format de sortie et votre langue, le bloc de code ci-dessus apparaîtra en surbrillance, avec des lignes numérotées. (Pour savoir quelles langues sont prises en charge, tapez pandoc --list-highlight-languages.) Sinon, le bloc de code ci-dessus apparaîtra comme suit :

<pre id="mycode" class="haskell numberLines" startFrom="100">
  <code>
  ...
  </code>
</pre>

La classe numberLines (ou number-lines) fera en sorte que les lignes du bloc de code soient numérotées, en commençant par 1 ou par la valeur de l'attribut startFrom. La classe lineAnchors (ou line-anchors) fera en sorte que les lignes soient des ancres cliquables dans la sortie HTML.

Un formulaire de raccourci peut également être utilisé pour spécifier la langue du bloc de code :

```haskell
qsort [] = []
```

Ce qui est équivalent à :

``` {.haskell}
qsort [] = []
```

Si l'extension fenced_code_attributes est désactivée, mais l'entrée contient un ou plusieurs attributs de classe pour le bloc de code, le premier attribut de classe sera imprimé après la clôture ouvrante comme un mot vide.

Pour éviter toute mise en évidence, utilisez la fonction --no-highlight flag. To set the highlighting style, use --highlight-style. Pour plus d'informations sur la mise en évidence, voir Syntax highlighting, ci-dessous.

Blocs Ligne

Extension: line_blocks

Un bloc de lignes est une séquence de lignes commençant par une barre verticale (|) suivie d'un espace. La division en lignes sera préservée dans la sortie, tout comme les espaces de tête de ligne ; sinon, les lignes seront formatées en Markdown. Ceci est utile pour les vers et les adresses :

| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718

Les lignes peuvent être forcées en fin de ligne si nécessaire, mais la ligne de continuation doit commencer par un espace.

| The Right Honorable Most Venerable and Righteous Samuel L.
  Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718

Cette syntaxe est empruntée à reStructuredText.

Listes

Listes à puces

Une liste à puces est une liste d'éléments d'une liste à puces. Une liste à puces commence par une puce (*, +, ou -). Voici un exemple simple :

* one
* two
* three

Il en résultera une liste "compacte". Si vous voulez une liste "libre", dans laquelle chaque élément est formaté en paragraphe, mettez des espaces entre les éléments :

* one

* two

* three

Les puces n'ont pas besoin d'être alignées avec la marge de gauche ; elles peuvent être indentées d'un, deux ou trois espaces. La puce doit être suivie d'un espace.

Les éléments de la liste ont une meilleure apparence si les lignes suivantes affleurent avec la première ligne (après la puce) :

* here is my first
  list item.
* and my second.

Mais Markdown permet aussi un format "paresseux" :

* here is my first
list item.
* and my second.

Block content in list items

Un élément de liste peut contenir plusieurs paragraphes et d'autres contenus au niveau des blocs. Toutefois, les paragraphes suivants doivent être précédés d'une ligne blanche et être en retrait pour s'aligner sur le premier contenu non spatial après le marqueur de liste.

  * First paragraph.

    Continued.

  * Second paragraph. With a code block, which must be indented
    eight spaces:

        { code }

Exception : si le marqueur de liste est suivi d'un bloc de code indenté, qui doit commencer 5 espaces après le marqueur de liste, alors les paragraphes suivants doivent commencer deux colonnes après le dernier caractère du marqueur de liste :

*     code

  continuation paragraph

Les éléments de la liste peuvent inclure d'autres listes. Dans ce cas, la ligne blanche précédente est facultative. La liste imbriquée doit être mise en retrait pour s'aligner sur le premier caractère non espace après le marqueur de liste de l'élément de liste qui la contient.

* fruits
  + apples
    - macintosh
    - red delicious
  + pears
  + peaches
* vegetables
  + broccoli
  + chard

Comme indiqué ci-dessus, Markdown vous permet d'écrire les éléments de la liste "paresseusement", au lieu d'indenter les lignes de continuation. Toutefois, si un élément de liste comporte plusieurs paragraphes ou d'autres blocs, la première ligne de chacun doit être mise en retrait.

+ A lazy, lazy, list
item.

+ Another one; this looks
bad but is legal.

    Second paragraph of second
list item.

Listes ordonnées

Les listes ordonnées fonctionnent comme les listes à puces, sauf que les éléments commencent par des énumérateurs plutôt que par des puces.

Dans le Markdown standard, les énumérateurs sont des nombres décimaux suivis d'un point et d'un espace. Les nombres eux-mêmes sont ignorés, il n'y a donc pas de différence entre cette liste :

1.  one
2.  two
3.  three

et celle-là :

5.  one
7.  two
1.  three

Extension: fancy_lists

Contrairement au système standard de Markdown, pandoc permet de marquer les articles d'une liste ordonnée avec des lettres majuscules et minuscules et des chiffres romains, en plus des chiffres arabes. Les marques de liste peuvent être mises entre parenthèses ou suivies d'une seule parenthèse droite ou d'un point. Ils doivent être séparés du texte qui suit par au moins un espace et, si le marqueur de liste est une lettre majuscule avec un point, par au moins deux espaces.1

L' extension fancy_lists autorise également ‘#’ à être utilisé comme marqueur de liste ordonnée à la place d'un chiffre :

#. one
#. two

Extension: startnum

Pandoc fait également attention au type de marqueur de liste utilisé, et au numéro de départ, et ces deux éléments sont préservés dans la mesure du possible dans le format de sortie. Ainsi, ce qui suit donne une liste avec des chiffres suivis d'une seule parenthèse, commençant par 9, et une sous-liste avec des chiffres romains minuscules :

 9)  Ninth
10)  Tenth
11)  Eleventh
       i. subone
      ii. subtwo
     iii. subthree

Pandoc commencera une nouvelle liste chaque fois qu'un type différent de marqueur de liste sera utilisé. Ainsi, trois listes seront créées :

(2) Two
(5) Three
1.  Four
*   Five

Si des marqueurs de liste par défaut sont souhaités, utilisez #.:

#.  one
#.  two
#.  three

Extension: task_lists

Pandoc prend en charge les listes de tâches, en utilisant la syntaxe de GitHub-Flavored Markdown.

- [ ] an unchecked task list item
- [x] checked item

Listes de définition

Extension: definition_lists

Pandoc prend en charge les listes de définition, en utilisant la syntaxe de PHP Markdown Extra avec certaines extensions.2

Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.

Chaque terme doit tenir sur une ligne, qui peut éventuellement être suivie d'une ligne blanche, et doit être suivi d'une ou plusieurs définitions. Une définition commence par un deux-points ou un tilde, qui peuvent être indentés d'un ou deux espaces.

Un terme peut avoir plusieurs définitions, et chaque définition peut être constituée d'un ou plusieurs éléments de bloc (paragraphe, bloc de code, liste, etc.), chacun étant indenté de quatre espaces ou d'un tabulateur. Le corps de la définition (y compris la première ligne, à l'exception du deux-points ou du tilde) doit être indenté de quatre espaces. Cependant, comme pour les autres listes Markdown, vous pouvez "paresseusement" omettre l'indentation, sauf au début d'un paragraphe ou d'un autre élément de bloc :

Term 1

:   Definition
with lazy continuation.

    Second paragraph of the definition.

Si vous laissez un espace avant la définition (comme dans l'exemple ci-dessus), le texte de la définition sera traité comme un paragraphe. Dans certains formats de sortie, cela signifie un plus grand espacement entre les paires terme/définition. Pour une liste de définitions plus compacte, omettez l'espace avant la définition :

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b

Notez que l'espace entre les éléments d'une liste de définitions est obligatoire. (Une variante qui assouplit cette exigence, mais qui interdit l'enroulement dur "paresseux", peut être activée avec compact_definition_lists: voir Non-pandoc extensions, ci-dessous.)

Listes d'exemples numéroté

Extension: example_lists

Le marqueur de listes spécial @ peut être utilisé pour des exemples numérotés de manière séquentielle. Le premier élément de la liste avec un marqueur @ sera numéroté ‘1’, le suivant ‘2’, etc.., tout au long du document. Il n'est pas nécessaire que les exemples numérotés figurent dans une liste unique ; chaque nouvelle liste utilisant @ reprendra là où la dernière s'est arrêtée. Ainsi, par exemple :

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).

Les exemples numérotés peuvent être étiquetés et mentionnés ailleurs dans le document :

(@good)  This is a good example.

As (@good) illustrates, ...

L'étiquette peut être une chaîne de caractères alphanumériques, un trait de soulignement ou un trait d'union.

Note : les paragraphes de suite dans les listes d'exemples doivent toujours être indentés de quatre espaces, quelle que soit la longueur du marqueur de liste. Autrement dit, les listes d'exemples se comportent toujours comme si l'extensionfour_space_rule est utilisée. En effet, les étiquettes d'exemple ont tendance à être longues et il serait difficile d'indenter le contenu jusqu'au premier caractère différent d'une espace après l'étiquette.

Compact and loose lists

Pandoc se comporte différemment de Markdown.pl sur certains "cas marginaux" impliquant des listes. Considérez cette source :

+   First
+   Second:
    -   Fee
    -   Fie
    -   Foe

+   Third

Pandoc transforme cela en une "liste compacte" (sans tags <p> autour de “First”, “Second”, ou “Third”), alors que Markdown ajoute les étiquettes <p> autour de “Second” et “Third” (mais pas “First”), à cause de l'espace vide autour de "Third". Pandoc suit une règle simple : si le texte est suivi d'une ligne blanche, il est traité comme un paragraphe. Puisque "Second" est suivi d'une liste, et non d'une ligne blanche, il n'est pas traité comme un paragraphe. Le fait que la liste soit suivie d'une ligne blanche n'a pas d'importance. (Note : Pandoc fonctionne de cette manière même lorsque le format markdown_strict est specifié. Ce comportement est conforme à la description syntaxique officielle de Markdown, même s'il est différent de celui de Markdown.pl.)

Terminer une liste

Que faire si vous voulez mettre un bloc de code indenté après une liste ?

-   item one
-   item two

    { my code block }

Des problèmes ! Ici, pandoc (comme d'autres implémentations de Markdown) traitera { my code block } comme deuxième paragraphe du point 2, et non comme bloc de code.

Pour "couper" la liste après le point deux, vous pouvez insérer un contenu non indenté, comme un commentaire HTML, qui ne produira pas de sortie visible dans un format quelconque :

-   item one
-   item two

<!-- end of list -->

    { my code block }

Vous pouvez utiliser la même astuce si vous voulez deux listes consécutives au lieu d'une seule grande liste :

1.  one
2.  two
3.  three

<!-- -->

1.  uno
2.  dos
3.  tres

Horizontal rules

Une ligne contenant une rangée de trois ou plus de caractères *, -, ou _ (éventuellement séparées par des espaces) produit une règle horizontale :

*  *  *  *

---------------

Tableaux

Quatre types de tableaux peuvent être utilisés. Les trois premiers types supposent l'utilisation d'une police à largeur fixe, telle que Courier. Le quatrième type peut être utilisé avec des polices à espacement proportionnel, car il ne nécessite pas d'aligner les colonnes.

Extension: table_captions

Une légende peut éventuellement être fournie avec les 4 types de tableaux (comme illustré dans les exemples ci-dessous). Une légende est un paragraphe qui commence par la chaîne de caractères Table: (ou simplement :), qui sera supprimée. Elle peut apparaître avant ou après le tableau.

Extension: simple_tables

De tableaux simples ressemblent à ceci :

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.

Les lignes d'en-tête et les lignes de tableau doivent tenir sur une seule ligne. L'alignement des colonnes est déterminé par la position du texte de l'en-tête par rapport à la ligne en pointillés qui se trouve en dessous :3

  • Si la ligne pointillée affleure le texte de l'en-tête sur le côté droit mais le dépasse sur la gauche, la colonne est alignée à droite.
  • Si la ligne pointillée affleure le texte de l'en-tête sur le côté gauche mais le dépasse sur la droite, la colonne est alignée à gauche.
  • Si la ligne pointillée dépasse le texte de l'en-tête des deux côtés, la colonne est centrée.
  • Si la ligne pointillée est au ras du texte de l'en-tête des deux côtés, l'alignement par défaut est utilisé (dans la plupart des cas, il sera à gauche).

Le tableau doit se terminer par une ligne blanche, ou une ligne de tirets suivie d'une ligne blanche.

La ligne d'en-tête de la colonne peut être omise, à condition qu'une ligne de tirets soit utilisée pour terminer le tableau. Par exemple, la ligne d'en-tête de la colonne peut être omise, à condition qu'une ligne pointillée soit utilisée pour terminer le tableau :

-------     ------ ----------   -------
     12     12        12             12
    123     123       123           123
      1     1          1              1
-------     ------ ----------   -------

Lorsque la ligne d'en-tête est omise, l'alignement des colonnes est déterminé sur la base de la première ligne du corps du tableau. Ainsi, dans les tableaux ci-dessus, les colonnes seraient respectivement alignées à droite, à gauche, au centre et à droite.

Extension: multiline_tables

Les tableaux multilignes permettent aux lignes d'en-tête et de tableau de couvrir plusieurs lignes de texte (mais les cellules qui couvrent plusieurs colonnes ou lignes du tableau ne sont pas prises en charge). Voici un exemple :

-------------------------------------------------------------
 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.

Ceux-ci fonctionnent comme de simples tableaux, mais avec les différences suivantes :

  • Ils doivent commencer par une rangée de tirets, avant le texte de l'en-tête (sauf si la rangée de l'en-tête est omise).
  • Ils doivent se terminer par une rangée de tirets, puis par une ligne blanche.
  • Les lignes doivent être séparées par des lignes blanches.

Dans les tableaux multilignes, l'analyseur de tableau fait attention à la largeur des colonnes, et les auteurs essaient de reproduire ces largeurs relatives dans le résultat. Ainsi, si vous trouvez qu'une des colonnes est trop étroite dans la sortie, essayez de l'élargir dans la source Markdown.

L'en-tête peut être omis dans les tableaux multilignes ainsi que dans les tableaux simples :

----------- ------- --------------- -------------------------
   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.
----------- ------- --------------- -------------------------

: Here's a multiline table without a header.

Il est possible qu'un tableau multiligne ne comporte qu'une seule ligne, mais celle-ci doit être suivie d'une ligne blanche (et ensuite de la ligne de tirets qui termine le tableau), ou le tableau peut être interprété comme un tableau simple.

Extension: grid_tables

Les tableaux quadrillés ressemblent à ceci :

: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

La rangée de =sépare l'en-tête du corps de la table, et peut être omise pour une table sans en-tête. Les cellules des tableaux à grille peuvent contenir des éléments de bloc arbitraires (plusieurs paragraphes, blocs de code, listes, etc.). Les cellules qui couvrent plusieurs colonnes ou lignes ne sont pas prises en charge. Les tableaux de grille peuvent être créés facilement en utilisant le mode tableau d'Emacs (M-x table-insert).

Les alignements peuvent être spécifiés comme dans les tableaux "pipe", en plaçant des deux-points aux limites de la ligne de séparation après l'en-tête :

+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Bananas       | $1.34         | built-in wrapper   |
+---------------+---------------+--------------------+

Pour les tableaux sans en-tête, les deux-points vont plutôt sur la ligne supérieure :

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+
Limitations des tableaux quadrillages

Pandoc ne prend pas en charge les tableaux à grille avec des étendues de lignes ou de colonnes. Cela signifie que ni le nombre variable de colonnes sur les lignes ni le nombre variable de lignes sur les colonnes ne sont pris en charge par Pandoc. Toutes les grilles doivent avoir le même nombre de colonnes dans chaque ligne et le même nombre de lignes dans chaque colonne. Par exemple, les exemples Docutils grid tables ne donnera pas le résultat escompté avec Pandoc.

Extension: pipe_tables

Les tableaux pipe ressemblent à ceci :

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.

La syntaxe est identique aux tableaux PHP Markdown Extra tables. Les caractères de début et de fin de pipe sont facultatifs, mais les pipes sont obligatoires entre toutes les colonnes. Les deux points indiquent l'alignement des colonnes comme indiqué. L'en-tête ne peut pas être omis. Pour simuler un tableau sans en-tête, il faut inclure un en-tête avec des cellules vides.

Comme les pipes indiquent les limites des colonnes, il n'est pas nécessaire d'aligner les colonnes verticalement, comme dans l'exemple ci-dessus. Il s'agit donc d'un tableau à pipe parfaitement légal (bien que laid) :

fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09

Les cellules des tableaux pipe ne peuvent pas contenir d'éléments de bloc comme des paragraphes et des listes, et ne peuvent pas s'étendre sur plusieurs lignes. Si un tableau pipe contient une ligne dont le contenu imprimable est plus large que la largeur de la colonne (voir --columns), le tableau prendra alors toute la largeur du texte et le contenu des cellules s'enveloppera, la largeur relative des cellules étant déterminée par le nombre de tirets dans la ligne séparant l'en-tête du tableau du corps du tableau. (Par exemple ---|- rendrait la première colonne 3/4 et la deuxième colonne 1/4 de la largeur du texte intégral). En revanche, si aucune ligne n'est plus large que la largeur de la colonne, le contenu des cellules ne sera pas "enveloppé", et les cellules seront dimensionnées en fonction de leur contenu.

Note : pandoc reconnaît également les tableaux de pipe de la forme suivante, tels qu'ils peuvent être produits par le mode orgtbl d'Emacs :

| One | Two   |
|-----+-------|
| my  | table |
| is  | nice  |

La différence est l'usage de + au lieu de |. Les autres fonctions de orgtbl ne sont pas prises en charge. En particulier, pour obtenir un alignement des colonnes sans défaut, vous devrez ajouter des deux-points comme ci-dessus.

Blocs de métadonnées

Extension: pandoc_title_block

Si le fichier commence par un bloc titre

% title
% author(s) (separated by semicolons)
% date

il sera analysé comme une information bibliographique, et non comme un texte ordinaire. (Il sera utilisé, par exemple, dans le titre d'une sortie autonome LaTeX ou HTML). Le bloc peut contenir uniquement un titre, un titre et un auteur, ou les trois éléments. Si vous voulez inclure un auteur mais pas de titre, ou un titre et une date mais pas d'auteur, vous avez besoin d'une ligne blanche :

%
% Author

% My title
%
% June 15, 2006

Le titre peut occuper plusieurs lignes, mais les lignes de continuation doivent commencer par un espace avant, donc :

% My title
  on multiple lines

Si un document a plusieurs auteurs, les auteurs peuvent être placés sur des lignes séparées avec un espace avant, ou séparés par des points-virgules, ou les deux. Ainsi, tous les éléments suivants sont équivalents :

% Author One
  Author Two

% Author One; Author Two

% Author One;
  Author Two

La date doit tenir sur une ligne.

Les trois champs de métadonnées peuvent contenir un formatage standard en ligne (italique, liens, notes de bas de page, etc.).

Les blocs de titres seront toujours analysés, mais ils n'affecteront la sortie que lorsque l'option --standalone (-s est choisie) . En sortie HTML, les titres apparaîtront deux fois : une fois dans l'en-tête du document - c'est le titre qui apparaîtra en haut de la fenêtre dans un navigateur - et une fois au début du corps du document. Le titre dans l'en-tête du document peut comporter un préfixe facultatif (option --title-prefix ou -T). Le titre dans le corps apparaît comme un élément H1 avec la classe "title", il peut donc être supprimé ou reformaté avec le CSS. Si un préfixe de titre est spécifié avec -T et qu'aucun bloc titre n'apparaît dans le document, le préfixe du titre sera utilisé seul comme titre HTML.

L'auteur Page de manuel extrait de la ligne de titre un titre, un numéro de section de la page de manuel et d'autres informations d'en-tête et de pied de page. Le titre est supposé être le premier mot de la ligne de titre, qui peut éventuellement se terminer par un numéro de section (à un seul chiffre) entre parenthèses. (Il ne doit pas y avoir d'espace entre le titre et les parenthèses.) Tout ce qui suit est supposé être un texte supplémentaire de pied de page et d'en-tête. Un caractère de pipe unique (|) devrait être utilisé pour séparer le texte du pied de page du texte de l'en-tête. Ainsi,

% PANDOC(1)

donnera une page de manuel avec le titre PANDOCet la  section 1.

% PANDOC(1) Pandoc User Manuals

aura également "manuels d'utilisation Pandoc" dans le bas de page.

% PANDOC(1) Pandoc User Manuals | Version 4.0

aura également "Version 4.0" dans l'en-tête.

Extension: yaml_metadata_block

Un bloc de métadonnées YAML est un objet YAML valide, délimité par une ligne de 3 tirets (---) au-dessus et une ligne de 3 tirets en-dessous (---) or 3 points (...) en-dessous. Un bloc de métadonnées YAML peut se trouver n'importe où dans le document, mais s'il ne se trouve pas au début, il doit être précédé d'une ligne blanche. (Notez qu'en raison de la façon dont pandoc concatène les fichiers d'entrée lorsque plusieurs sont fournis, vous pouvez également conserver les métadonnées dans un fichier YAML séparé et le transmettre à pandoc en tant qu'argument, avec vos fichiers Markdown :

pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html

Assurez-vous simplement que le fichier YAML commence par --- et termine avec --- ou ....) Vous pouvez également utiliser l' option --metadata-file. Cependant, cette approche ne permet pas de référencer le contenu (comme les notes de bas de page) du document principal de saisie de Markdown.

Les métadonnées seront extraites des champs de l'objet YAML et ajoutées à toutes les métadonnées de document existantes. Les métadonnées peuvent contenir des listes et des objets (imbriqués arbitrairement), mais toutes les chaînes scalaires ("string scalars") seront interprétées comme des Markdown. Les champs dont les noms se terminent par un trait de soulignement seront ignorés par pandoc. (Ils peuvent se voir attribuer un rôle par des processeurs externes.) Les noms de champs ne doivent pas être interprétables comme des numéros YAML ou des valeurs booléennes (donc, par exemple, yes, True, et 15 ne peuvent pas être utilisés comme noms de champs).

Un document peut contenir plusieurs blocs de métadonnées. Si deux blocs de métadonnées tentent de définir le même champ, la valeur du deuxième bloc sera prise.

Lorsque pandoc est utilisé avec -t markdown pour créer un document Markdown, un bloc de métadonnées YAML ne sera produit que si l'option -s/--standalone est utilisée. Toutes les métadonnées apparaîtront en un seul bloc au début du document.

Il est à noter que les règles d'échappement de YAML doivent être respectées. Ainsi, par exemple, si un titre contient un deux-points, il doit être cité. Le caractère pipe (|) peut être utilisé pour commencer un bloc indenté qui sera interprété littéralement, sans qu'il soit nécessaire de s'échapper. Ce formulaire est nécessaire lorsque le champ contient des lignes vierges ou un formatage au niveau du bloc :

---
title:  'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...

Les variables du modèle seront définies automatiquement à partir des métadonnées. Ainsi, par exemple, en écrivant du HTML, la variable abstract sera réglé sur l'équivalent HTML du Markdown dans le champ abstract :

<p>This is the abstract.</p>
<p>It consists of two paragraphs.</p>

Les variables peuvent contenir des structures YAML arbitraires, mais le modèle doit correspondre à cette structure. La  variable authordans les modèles par défaut s'attend à une simple liste ou chaîne de caractères, mais peut être modifié pour supporter des structures plus compliquées. La combinaison suivante, par exemple, ajouterait une affiliation à l'auteur si elle est donnée :

---
title: The document title
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
...

Pour utiliser les auteurs structurés dans l'exemple ci-dessus, vous auriez besoin d'un modèle personnalisé :

$for(author)$
$if(author.name)$
$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
$else$
$author$
$endif$
$endfor$

Le contenu brut à inclure dans l'en-tête du document peut être spécifié en utilisant header-includes; cependant, il est important de marquer ce contenu comme un code brut pour un format de sortie particulier, en utilisant l'extension raw_attribute extension), sinon elle sera interprétée comme un markdown. Par exemple :

header-includes:
- |
  ```{=latex}
  \let\oldsection\section
  \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
  ```

Les échappements de backslash (touche oblique inverse)

Extension: all_symbols_escapable

Sauf à l'intérieur d'un bloc de code ou d'un code en ligne, toute ponctuation ou tout caractère d'espacement précédé d'une barre oblique inversée sera traité littéralement, même s'il indique normalement un formatage. Ainsi, par exemple, si l'on écrit

*\*hello\**

on aura

<em>*hello*</em>

au lieu de

<strong>hello</strong>

Cette règle est plus facile à retenir que la règle standard de Markdown, qui ne permet d'échapper que les caractères suivants

\`*_{}[]()>#+-.!

(Toutefois si le format markdown_strict est utilisé, la règle standard de Markdown sera utilisée).

Un espace en retrait est analysé comme un espace insécable. Dans la sortie TeX, il apparaîtra comme ~. En sortie HTML et XML, il apparaîtra sous la forme d'un caractère espace insécable unicode (notez qu'il semblera donc en fait "invisible" dans la source HTML générée ; vous pouvez toujours utiliser l'option en ligne de commande --ascii pour la faire apparaître comme une entité explicite).

Un saut deligne échappé par une barre oblique inversée (c'est-à-dire une barre oblique inversée en fin de ligne) est analysé comme un saut de ligne. Il apparaîtra dans la sortie TeX comme \\ et en HTML comme <br /> C'est une bonne alternative à la méthode "invisible" de Markdown qui consiste à indiquer les ruptures de ligne en utilisant deux espaces à la fin d'une ligne.

Les échappements par barre oblique inversée ne fonctionnent pas dans les contextes textuels (ou "verbatim").

Formatage en ligne

Emphasis

To emphasize some text, surround it with *s or _, like this:

This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.

Double * or _ produces strong emphasis:

This is **strong emphasis** and __with underscores__.

A * or _ character surrounded by spaces, or backslash-escaped, will not trigger emphasis:

This is * not emphasized *, and \*neither is this\*.

Extension: intraword_underscores

Comme _ est parfois utilisé à l'intérieur de mots et d'identifiants, pandoc n'interprète pas un _ entouré de caractères alphanumériques comme marqueur d'accentuation. Si vous souhaitez mettre l'accent sur une partie seulement d'un mot, utilisez *:

feas*ible*, not feas*able*.

Rayer du texte

Extension: strikeout

Pour rayer une section de texte d'une ligne horizontale, commencez et terminez-la par ~~. Ainsi, par exemple,

This ~~is deleted text.~~

Exposants et indices

Extension: superscript, subscript

Les exposants peuvent être écrits en entourant le texte par les caractères ^; les indices peuvent être écrits en entourant le texte par les caractères ~. Par exemple,

H~2~O is a liquid.  2^10^ is 1024.

Le texte entre ^...^ ou ~...~ ne peut pas contenir d'espaces ou de nouvelles lignes. Si le texte en exposant ou en abrégé contient des espaces, ces derniers doivent être séparés par des barres obliques inverses. (Ceci afin d'éviter les mises en exposant et en indice accidentelles par l'utilisation ordinaire de ~et  ^, et aussi de mauvaises interactions avec les notes de bas de page). Ainsi, si vous voulez la lettre P avec "un chat" en indice, utilisez P~a\ cat~et pas,  P~a cat~.

Verbatim

Pour faire une courte séquence de texte mot à mot, mettez-la à l'intérieur des backticks (Fr : AltGr-7) :

What is the difference between `>>=` and `>>`?

Si le texte verbatim comprend une backtick, utilisez des backtick doubles :

Here is a literal backtick `` ` ``.

(Les espaces après les baguettes d'ouverture et avant les baguettes de fermeture seront ignorés).

La règle générale est qu'un texte verbatim commence par une série de backticks consécutives (éventuellement suivie d'un espace) et se termine par une série du même nombre de baguettes (éventuellement précédée d'un espace).

Il est à noter que les backslash-escapes (et autres constructions Markdown) ne fonctionnent pas dans les contextes verbatim :

This is a backslash followed by an asterisk: `\*`.

Extension: inline_code_attributes

Les attributs peuvent être joints au texte verbatim, tout comme pour fenced code blocks:

`<$>`{.haskell}

Petites capitales

To write small caps, use the smallcaps class:

[Small caps]{.smallcaps}

Or, without the bracketed_spans extension:

<span class="smallcaps">Small caps</span>

For compatibility with other Markdown flavors, CSS is also supported:

<span style="font-variant:small-caps;">Small caps</span>

Cela fonctionnera dans tous les formats de sortie qui supportent les petites capitales.

Maths

Extension: tex_math_dollars

Tout ce qui se situe entre deux caractères $ sera traité comme des mathématiques TeX. Le$ ouvrant doit avoir un caractère non-espace immédiatement à sa droite, tandis que le$ fermant doit avoir un caractère non-espace immédiatement à sa gauche, et ne doit pas être suivi immédiatement d'un chiffre. Ainsi, $20,000 and $30,000 ne sera pas analysé comme des maths. Si, pour une raison quelconque, vous devez joindre les caractères $ dans du texte au sens littéral, faites-les précéder d'une barre oblique inversée et ils ne seront pas interprêtés comme délimiteurs mathématiques.

Pour afficher des maths, utiliser des délimiteurs $$. (Dans ce cas, les délimiteurs doivent être séparatés de la formule par une espace.)

Les mathématiques TeX seront imprimées dans tous les formats de sortie. La manière dont il est rendu dépend du format de sortie :

LaTeX
It will appear verbatim surrounded by \(...\) (for inline math) or \[...\] (for display math).

Markdown, Emacs Org mode, ConTeXt, ZimWiki
It will appear verbatim surrounded by $...$ (for inline math) or $$...$$ (for display math).

XWiki
It will appear verbatim surrounded by {{formula}}..{{/formula}}.

reStructuredText
It will be rendered using an interpreted text role :math:.

AsciiDoc
For AsciiDoc output format (-t asciidoc) it will appear verbatim surrounded by latexmath:[$...$] (for inline math) or [latexmath]++++\[...\]+++ (for display math). For AsciiDoctor output format (-t asciidoctor) the LaTex delimiters ($..$ and \[..\]) are omitted.

Texinfo
It will be rendered inside a @math command.

roff man, Jira markup
It will be rendered verbatim without $’s.

MediaWiki, DokuWiki
It will be rendered inside <math> tags.

Textile
It will be rendered inside <span class="math"> tags.

RTF, OpenDocument
It will be rendered, if possible, using Unicode characters, and will otherwise appear verbatim.

ODT
It will be rendered, if possible, using MathML.

DocBook
If the --mathml flag is used, it will be rendered using MathML in an inlineequation or informalequation tag. Otherwise it will be rendered, if possible, using Unicode characters.

Docx
It will be rendered using OMML math markup.

FictionBook2
If the --webtex option is used, formulas are rendered as images using CodeCogs or other compatible web service, downloaded and embedded in the e-book. Otherwise, they will appear verbatim.

HTML, Slidy, DZSlides, S5, EPUB
The way math is rendered in HTML will depend on the command-line options selected. Therefore see Math rendering in HTML above.

HTML brut

Extension: raw_html

Markdown vous permet d'insérer du HTML brut (ou DocBook) n'importe où dans un document (sauf dans les contextes verbatim, où <, >, et & sont interprétés littéralement). (Techniquement, il ne s'agit pas d'une extension, puisque la norme Markdown le permet, mais il a été fait une extension pour qu'il puisse être désactivé si désiré).

Le HTML brut est transmis tel quel en HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, et Textile output, et supprimé dans les autres formats.

Pour une façon plus explicite d'inclure du HTML brut dans un document Markdown, voir l'extension raw_attribute extension.

Dans le format CommonMark, si raw_html est activée, les exposants, les indices, les biffures et les petites capitales seront représentés en HTML. Dans le cas contraire, les repères (fallbacks) en texte clair seront utilisés. Notez que même si  raw_html est désactivé, les tableaux seront rendus avec la syntaxe HTML s'ils ne peuvent pas utiliser la syntaxe du pipe.

Extension: markdown_in_html_blocks

Le Markdown standard vous permet d'inclure des "blocs" HTML : des blocs de HTML entre des balises symétriques qui sont séparées du texte environnant par des lignes blanches, et dont le début et la fin se trouvent dans la marge gauche. À l'intérieur de ces blocs, tout est interprété comme du HTML, et non du Markdown ; donc (par exemple), *ne signifie pas "mise en emphase".

Pandoc se comporte de cette façon lorsque le format markdown_strictest utilisé ; mais par défaut, pandoc interprète le matériel entre les balises de bloc HTML comme étant du Markdown. Ainsi, par exemple, pandoc transformera

<table>
<tr>
<td>*one*</td>
<td>[a link](https://google.com)</td>
</tr>
</table>

en

<table>
<tr>
<td><em>one</em></td>
<td><a href="https://google.com">a link</a></td>
</tr>
</table>

alors que Markdown.pl le conservera tel quel.

Il y a une exception à cette règle : le texte entre les balises <script>et  <style> n'est pas interprétée comme du Markdown.

Cet écart par rapport au standard Markdown devrait faciliter le mélange de Markdown avec des éléments de bloc HTML. Par exemple, on peut entourer un bloc de texte Markdown avec des balises <div> sans empêcher qu'il soit interprété comme un Markdown.

Extension: native_divs

Utilise les blocs pandoc natifs Divpour du contenu entre balises <div>. Pour l'essentiel, cela devrait donner le même résultat que markdown_in_html_blocks, mais il est plus facile d'écrire des filtres pandoc pour manipuler des groupes de blocs.

Extension: native_spans

Utilise les blocs pandoc Span natifs pour le contenu entre balises <span>. Pour l'essentiel, cela devrait donner le même résultat que raw_html, mais il est plus facile d'écrire des filtres pandoc pour manipuler des groupes d'en ligne ("inlines").

Extension: raw_tex

En plus du HTML brut, pandoc permet d'inclure du LaTeX, TeX et ConTeXt brut dans un document. Les commandes TeX en ligne seront préservées et transmises telles quelles aux auteurs LaTeX et ConTeXt. Ainsi, par exemple, vous pouvez utiliser LaTeX pour inclure des citations BibTeX :

This result was proved in \cite{jones.1967}.

Notez que dans les environnements LaTeX, comme

\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}

le matériel entre les balises de début et de fin sera interprété comme du LaTeX brut, et non comme du Markdown.

Pour une manière plus explicite et plus souple d'inclure du TeX brut dans un document Markdown, voir l'extension raw_attribute extension.

Le LaTeX en ligne est ignoré dans les formats de sortie autres que Markdown, LaTeX, le mode Emacs Org et ConTeXt.

Generic raw attribute

Extension: raw_attribute

Inline spans and fenced code blocks with a special kind of attribute will be parsed as raw content with the designated format. For example, the following produces a raw roff ms block:

```{=ms}
.MYMACRO
blah blah
```

And the following produces a raw html inline element:

This is `<a>html</a>`{=html}

This can be useful to insert raw xml into docx documents, e.g. a pagebreak:

```{=openxml}
<w:p>
  <w:r>
    <w:br w:type="page"/>
  </w:r>
</w:p>
```

The format name should match the target format name (see -t/--to, above, for a list, or use pandoc --list-output-formats). Use openxml for docx output, opendocument for odt output, html5 for epub3 output, html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output (depending on what you use for --pdf-engine).

This extension presupposes that the relevant kind of inline code or fenced code block is enabled. Thus, for example, to use a raw attribute with a backtick code block, backtick_code_blocks must be enabled.

The raw attribute cannot be combined with regular attributes.

LaTeX macros

Extension: latex_macros

Lorsque cette extension est activée, pandoc analyse les définitions de macros LaTeX et applique les macros résultantes à tous les calculs LaTeX et LaTeX brut. Ainsi, par exemple, ce qui suit fonctionnera dans tous les formats de sortie, pas seulement LaTeX :

\newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$

Note that LaTeX macros will not be applied if they occur inside a raw span or block marked with the raw_attribute extension.

Lorsque latex_macros est désactivé, le LaTeX brut et les mathématiques n'auront pas de macros appliquées. Cette approche est généralement préférable lorsque vous visez le LaTeX ou le PDF.

Les définitions de macros en LaTeX ne seront transmises en tant que LaTeX brut que si latex_macros n'est pas activée. Les définitions des macros dans la source Markdown (ou d'autres formats permettant raw_tex) sera transmise indépendamment du fait que latex_macrosest activé .

Liens

Markdown permet de spécifier les liens de plusieurs façons.

Automatic links

Si vous indiquez une URL ou une adresse électronique entre crochets, elle deviendra un lien :

<https://google.com>
<[email protected]>

Liens en ligne

Un lien en ligne se compose du texte du lien entre crochets, suivi de l'URL entre parenthèses. (Facultativement, l'URL peut être suivie d'un titre de lien, entre guillemets).

This is an [inline link](/url), and here's [one with
a title](https://fsf.org "click here for a good time!").

Il ne peut y avoir aucun espace entre la partie entre crochets et la partie entre parenthèses. Le texte du lien peut contenir une mise en forme (comme l'accentuation), mais pas le titre.

Les adresses électroniques dans les liens en ligne ne sont pas autodétectées, elles doivent donc être préfixées par mailto:

[Write me!](mailto:[email protected])

Liens vers des références

Un lien de référence explicite comporte deux parties, le lien lui-même et la définition du lien, qui peut se trouver ailleurs dans le document (soit avant, soit après le lien).

Le lien se compose du texte du lien entre crochets, suivi d'une étiquette entre crochets. (Il ne peut y avoir d'espace entre les deux, sauf si l'extension spaced_reference_links est validée.) La définition du lien se compose de l'étiquette entre crochets, suivie des deux points et d'un espace, puis de l'URL et, éventuellement (après un espace), d'un titre de lien entre guillemets ou entre parenthèses. L'étiquette ne doit pas pouvoir être analysée comme une citation (en supposant que l'extension citations est activée): Les citations ont la priorité sur les étiquettes de liens.

Voici quelques exemples :

[my label 1]: /foo/bar.html  "My title, optional"
[my label 2]: /foo
[my label 3]: https://fsf.org (The free software foundation)
[my label 4]: /bar#special  'A title in single quotes'

L'URL peut éventuellement être entourée des signes <> :

[my label 5]: <http://foo.bar.baz>

Le titre peut aller sur la ligne suivante

[my label 3]: https://fsf.org
  "The free software foundation"

Notez que les étiquettes de liens ne sont pas sensibles à la casse. Donc, cela va fonctionner :

Here is [my link][FOO]

[Foo]: /bar/baz

Dans un lien de référence implicite, la deuxième paire de crochets est vide :

See [my website][].

[my website]: http://foo.bar.baz

Note: Dans Markdown.pl et la plupart des autres implémentations de Markdown, les définitions de liens de référence ne peuvent pas se produire dans des constructions imbriquées telles que des éléments de liste ou des citations en bloc. Pandoc lève cette apparente restriction arbitraire. Ce qui suit est donc très bien dans le cadre de pandoc, mais pas dans la plupart des autres mises en œuvre :

> My block [quote].
>
> [quote]: /foo

Extension: shortcut_reference_links

Dans un lien de référence de raccourci, la deuxième paire de crochets peut être entièrement omise :

See [my website].

[my website]: http://foo.bar.baz

Liens internes

Pour établir un lien avec une autre section du même document, utilisez l'identifiant généré automatiquement (voir Heading identifiers). Par exemple:

See the [Introduction](#introduction).

ou

See the [Introduction].

[Introduction]: #introduction

Les liens internes sont actuellement pris en charge pour les formats HTML (y compris les diaporamas HTML et EPUB), LaTeX et ConTeXt.

Images

Un lien immédiatement précédé d'un ! sera traitée comme une image. Le texte du lien sera utilisé comme texte alternatif de l'image :

![la lune](lalune.jpg "Voyage to the moon")

![movie reel]

[movie reel]: movie.gif

Extension: implicit_figures

Une image avec un texte alt non vide, se produisant par lui-même dans un paragraphe, sera rendue comme une figure avec une légende. Le texte alt de l'image sera utilisé comme légende.

![This is the caption](/url/of/image.png)

La manière dont cela est rendu dépend du format de sortie. Certains formats de sortie (par exemple, RTF) ne permettent pas encore d'obtenir des chiffres. Dans ces formats, vous obtiendrez simplement une image dans un paragraphe, sans légende.

Si vous voulez juste une image en ligne régulière, assurez-vous que ce n'est pas la seule chose dans le paragraphe. Une façon de le faire est d'insérer un espace insécable après l'image :

![This image won't be a figure](/url/of/image.png)\

Notez que dans les diaporamas de reveal.js, une image dans un paragraphe à elle seule qui a la classe stretch remplira l'écran, et les balises de légende et de figure seront omises.

Extension: link_attributes

Des attributs peuvent être définis sur les liens et les images :

An inline ![image](foo.jpg){#id .class width=30 height=20px}
and a reference ![image][ref] with attributes.

[ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}

(Cette syntaxe est compatible avec PHP Markdown Extra lorsque seuls #idet  .class sont utilisés.)

Pour HTML et EPUB, tous les attributs connus de HTML5 sauf widthet  height (mais incluant srcset et sizes) sont passés tels quels. Les attributs inconnus sont transmis en tant qu'attributs personnalisés, avec data- prepended. Les autres auteurs ignorent les attributs qui ne sont pas spécifiquement pris en charge par leur format de sortie.

Les attributs width et heightsur les images sont traités spécialement . Lorsqu'elle est utilisée sans unité, l'unité est supposée être le pixel. Toutefois, les identificateurs d'unité suivants peuvent être utilisés : px, cm, mm, in, inch et %. Il ne doit y avoir aucun espace entre le nombre et l'unité. Par exemple :

![](file.jpg){ width=50% }
  • Les dimensions sont converties en pouces pour une sortie dans des formats de page comme LaTeX. Les dimensions sont converties en pixels pour une sortie au format HTML. Utilisez l'option --dpi spécifier le nombre de pixels par pouce. La valeur par défaut est de 96 dpi.
  • L'unité % est généralement relative à un certain espace disponible. Par exemple, l'exemple ci-dessus se traduira par ce qui suit.
    • HTML: <img href="file.jpg" style="width: 50%;" />
    • LaTeX: \includegraphics[width=0.5\textwidth,height=\textheight]{file.jpg} (Si vous utilisez un modèle personnalisé, vous devez configurer graphicx as in the default template.)
    • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
  • Some output formats have a notion of a class (ConTeXt) or a unique identifier (LaTeX \caption), or both (HTML).
  • When no width or height attributes are specified, the fallback is to look at the image resolution and the dpi metadata embedded in the image file.

Divs and Spans

En utilisant les extensions native_divset native_spans (voir ci-dessus), la syntaxe HTML peut être utilisé dans le cadre de Markdown pour créer des éléments Div et Span natifs dans l'AST pandoc (en opposition au HTML brut). Toutefois, il existe également une syntaxe plus agréable :

Extension: fenced_divs

Allow special fenced syntax for native Div blocks. A Div starts with a fence containing at least three consecutive colons plus some attributes. The attributes may optionally be followed by another string of consecutive colons. The attribute syntax is exactly as in fenced code blocks (see Extension: fenced_code_attributes). As with fenced code blocks, one can use either attributes in curly braces or a single unbraced word, which will be treated as a class name. The Div ends with another line containing a string of at least three consecutive colons. The fenced Div should be separated by blank lines from preceding and following blocks.

Example:

::::: {#special .sidebar}
Here is a paragraph.

And another.
:::::

Fenced divs can be nested. Opening fences are distinguished because they must have attributes:

::: Warning ::::::
This is a warning.

::: Danger
This is a warning within a warning.
:::
::::::::::::::::::

Fences without attributes are always closing fences. Unlike with fenced code blocks, the number of colons in the closing fence need not match the number in the opening fence. However, it can be helpful for visual clarity to use fences of different lengths to distinguish nested divs from their parents.

Extension: bracketed_spans

Une séquence d'inlines entre crochets, comme on le ferait pour commencer un lien, sera traitée comme un Span avec des attributs si elle est suivie immédiatement par des attributs :

[This is *some text*]{.class key="val"}

Footnotes

Extension: footnotes

Le Markdown de Pandoc permet d'ajouter des notes de bas de page, en utilisant la syntaxe suivante :

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

Les identificateurs dans les références de notes de bas de page ne doivent pas contenir d'espaces, de tabulations ou de nouvelles lignes. Ces identificateurs sont utilisés uniquement pour corréler la référence de la note de bas de page avec la note elle-même ; dans la sortie, les notes de bas de page seront numérotées séquentiellement.

Les notes de bas de page elles-mêmes ne doivent pas être placées à la fin du document. Ils peuvent apparaître n'importe où sauf à l'intérieur d'autres éléments de bloc (listes, blocs de citations, tableaux, etc.). Chaque note de bas de page doit être séparée du contenu environnant (y compris les autres notes de bas de page) par des lignes blanches.

Extension: inline_notes

Les notes de bas de page en ligne sont également autorisées (bien que, contrairement aux notes normales, elles ne puissent pas contenir plusieurs paragraphes). La syntaxe est la suivante :

Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]

Les notes de bas de page en ligne et régulières peuvent être mélangées librement.

Citations

Extension: citations

En utilisant un filtre externe, pandoc-citeproc pandoc peut générer automatiquement des citations et une bibliographie dans un certain nombre de styles. L'utilisation de base est,

pandoc --filter pandoc-citeproc myinput.txt

Pour utiliser cette fonction, vous devrez spécifier un fichier bibliographique à l'aide du champ de métadonnée bibliographydans une section de métadonnées  YAML, ou l'argument en ligne de commande --bibliography. Vous pouvez fournir plusieurs arguments --bibliographyou définir un champ de métadonnées  bibliography dans le tableau YAML, si vous souhaitez utiliser plusieurs fichiers bibliographiques. La bibliographie peut avoir n'importe lequel de ces formats :

Format File extension
BibLaTeX .bib
BibTeX .bibtex
Copac .copac
CSL JSON .json
CSL YAML .yaml
EndNote .enl
EndNote XML .xml
ISI .wos
MEDLINE .medline
MODS .mods
RIS .ris

Notez que .bib peut être utilisé avec les fichiers BibTeX et BibLaTeX ; utilisez .bibtexpour  forcer BibTeX.

Notez que pandoc-citeproc --bib2jsonet  pandoc-citeproc --bib2yaml peuvent produire des fichiers .json et .yaml depuis n'importe lequel des fichiers supportés.

Balises intra-champ : dans les bases de données BibTeX et BibLaTeX, pandoc-citeproc analyse un sous-ensemble du balisage LaTeX ; dans les bases de données CSL YAML, pandoc Markdown ; et dans les bases de données CSL JSON, un balisage HTML-like :

<i>...</i>
italics

<b>...</b>
bold

<span style="font-variant:small-caps;">...</span> or <sc>...</sc>
small capitals

<sub>...</sub>
subscript

<sup>...</sup>
superscript

<span class="nocase">...</span>
prevent a phrase from being capitalized as title case

pandoc-citeproc -j et -y convertissent autant que possible les formats CSL JSON et CSL YAML.

Au lieu de spécifier un fichier bibliographique en utilisant --bibliography ou le champ de métadonnées YAML bibliography vous pouvez inclure les données de citation directement dans le champ references des métadonnées YAML du document. Le champ doit contenir un tableau de références codées en YAML, par exemple :

---
references:
- type: article-journal
  id: WatsonCrick1953
  author:
  - family: Watson
    given: J. D.
  - family: Crick
    given: F. H. C.
  issued:
    date-parts:
    - - 1953
      - 4
      - 25
  title: 'Molecular structure of nucleic acids: a structure for deoxyribose
    nucleic acid'
  title-short: Molecular structure of nucleic acids
  container-title: Nature
  volume: 171
  issue: 4356
  page: 737-738
  DOI: 10.1038/171737a0
  URL: https://www.nature.com/articles/171737a0
  language: en-GB
...

(pandoc-citeproc --bib2yaml peut les produire à partir d'un fichier bibliographique dans l'un des formats pris en charge .)

Citations and references can be formatted using any style supported by the Citation Style Language, listed in the Zotero Style Repository. These files are specified using the --csl option or the csl metadata field. By default, pandoc-citeproc will use the Chicago Manual of Style author-date format. The CSL project provides further information on finding and editing styles.

To make your citations hyperlinks to the corresponding bibliography entries, add link-citations: true to your YAML metadata.

Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or _, and may contain alphanumerics, _, and internal punctuation characters (:.#$%&-+?<>~/). Here are some examples:

Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

pandoc-citeproc detects locator terms in the CSL locale files. Either abbreviated or unabbreviated forms are accepted. In the en-US locale, locator terms can be written in either singular or plural forms, as book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part, pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.; volume, vol./vols.; /¶¶; §/§§. If no locator term is used, “page” is assumed.

pandoc-citeproc will use heuristics to distinguish the locator from the suffix. In complex cases, the locator can be enclosed in curly braces (using pandoc-citeproc 0.15 and higher only):

[@smith{ii, A, D-Z}, with a suffix]
[@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]

A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text:

Smith says blah [-@smith04].

You can also write an in-text citation, as follows:

@smith04 says blah.

@smith04 [p. 33] says blah.

If the style calls for a list of works cited, it will be placed in a div with id refs, if one exists:

::: {#refs}
:::

Otherwise, it will be placed at the end of the document. Generation of the bibliography can be suppressed by setting suppress-bibliography: true in the YAML metadata.

If you wish the bibliography to have a section heading, you can set reference-section-title in the metadata, or put the heading at the beginning of the div with id refs (if you are using it) or at the end of your document:

last paragraph...

# References

The bibliography will be inserted after this heading. Note that the unnumbered class will be added to this heading, so that the section will not be numbered.

If you want to include items in the bibliography without actually citing them in the body text, you can define a dummy nocite metadata field and put the citations there:

---
nocite: |
  @item1, @item2
...

@item3

In this example, the document will contain a citation for item3 only, but the bibliography will contain entries for item1, item2, and item3.

It is possible to create a bibliography with all the citations, whether or not they appear in the document, by using a wildcard:

---
nocite: |
  @*
...

For LaTeX output, you can also use natbib or biblatex to render the bibliography. In order to do so, specify bibliography files as outlined above, and add --natbib or --biblatex argument to pandoc invocation. Bear in mind that bibliography files have to be in respective format (either BibTeX or BibLaTeX).

For more information, see the pandoc-citeproc man page.

Non-pandoc extensions

Les extensions syntaxiques Markdown suivantes ne sont pas activées par défaut dans pandoc, mais peuvent être activées en ajoutant +EXTENSION au nom du format, où EXTENSION est le nom de l'extension. Ainsi, par example, markdown+hard_line_breaks is Markdown with hard line breaks.

Extension: old_dashes

Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - before a numeral is an en-dash, and -- is an em-dash. This option only has an effect if smart is enabled. It is selected automatically for textile input.

Extension: angle_brackets_escapable

Allow < and > to be backslash-escaped, as they can be in GitHub flavored Markdown but not original Markdown. This is implied by pandoc’s default all_symbols_escapable.

Extension: lists_without_preceding_blankline

Permettre à une liste de se produire juste après un paragraphe, sans espace vide intermédiaire.

Extension: four_space_rule

Sélectionne le comportement pandoc <= 2.0 pour l'analyse des listes, de sorte que quatre espaces d'indentation sont nécessaires pour les paragraphes de continuation des éléments de la liste.

Extension: spaced_reference_links

Permettre des espaces entre les deux composantes d'un lien de référence, par exemple,

[foo] [bar].

Extension: hard_line_breaks

Toutes les nouvelles lignes d'un paragraphe doivent être interprétées comme des sauts de ligne au lieu d'espaces.

Extension: ignore_line_breaks

Il fait en sorte que les nouvelles lignes à l'intérieur d'un paragraphe soient ignorées, plutôt que d'être traitées comme des espaces ou des sauts de ligne. Cette option est destinée aux langues d'Asie de l'Est où les espaces ne sont pas utilisés entre les mots, mais où le texte est divisé en lignes pour plus de lisibilité.

Extension: east_asian_line_breaks

Fait en sorte que les nouveaux traits à l'intérieur d'un paragraphe soient ignorés, plutôt que d'être traités comme des espaces ou des sauts de ligne, lorsqu'ils se produisent entre deux caractères larges d'Asie de l'Est. C'est un meilleur choix que ignore_line_breaks pour les textes qui comprennent un mélange de caractères larges d'Asie de l'Est et d'autres caractères.

Extension: emoji

Analyse les émojis textuels comme :smile:en tant qu'émoticônes Unicode.

Extension: tex_math_single_backslash

Tout ce qui se trouve entre \(et  \) doit être interprété comme des calculs de TeX en ligne, et tout ce qui se trouve entre \[et  \] doit être interprété comme des calculs de TeX en affichage. Note: un inconvénient de cette extension est qu'elle empêche l'échappement de ( et [.

Extension: tex_math_double_backslash

Tout ce qui se situe entre \\(et  \\) doit être interprété comme un calcul TeX en ligne, et tout ce qui se situe entre \\[et  \\] doit être interprété comme un affichage TeX math.

Extension: markdown_attribute

Par défaut, pandoc interprète le matériel à l'intérieur des balises de niveau bloc comme étant du Markdown. Cette extension modifie le comportement de sorte que Markdown n'est analysé à l'intérieur des balises de niveau bloc que si les balises ont l'attribut markdown=1.

Extension: mmd_title_block

Permet un bloc titre de style MultiMarkdown en haut du document, par exemple:

Title:   My title
Author:  John Doe
Date:    September 1, 2008
Comment: This is a sample mmd title block, with
         a field spanning multiple lines.

Voir la documentation MultiMarkdown pour plus de détails. Si les fonctions pandoc_title_blockou  yaml_metadata_blocksont activées, elles auront la priorité sur  mmd_title_block.

Extension: abbreviations

Parses PHP Markdown Extra abbreviation keys, like

*[HTML]: Hypertext Markup Language

Notez que le modèle de document pandoc ne supporte pas les abréviations, donc si cette extension est activée, les clés d'abréviation sont simplement ignorées (au lieu d'être analysées comme des paragraphes).

Extension: autolink_bare_uris

Transforme tous les URI absolus en liens, même s'ils ne sont pas entourés d'accolades <...>.

Extension: mmd_link_attributes

Analyse les attributs de valeur clé de style multimarkdown sur les références de liens et d'images. Cette extension ne doit pas être confondue avec l'extension link_attributes.

This is a reference ![image][ref] with multimarkdown attributes.

[ref]: https://path.to/image "Image title" width=20px height=30px
       id=myId class="myClass1 myClass2"

Extension: mmd_header_identifiers

Analyse les identificateurs des titres de style "multimarkdown" (entre crochets, après le titre mais avant tout #de suivi dans un titre ATX).

Extension: compact_definition_lists

Active la syntaxe de définition de liste de pandoc 1.12.x et préc. Cette syntaxe diffère de celle décrite ci-dessus après Definition lists sur plusieurs points :

  • Pas de ligne vide requise entre des items consécutifs de la liste de définition.
  • Pour avoir une liste “tight” ou “compacte”, omettre l'espace entre les items consecutifs ; l'espace entre un terme et sa définition n'affecte rien.
  • Lazy wrapping of paragraphs is not allowed: the entire definition must be indented four spaces.4

Extension: gutenberg

Use Project Gutenberg conventions for plain output: all-caps for strong emphasis, surround by underscores for regular emphasis, add extra blank space around headings.

Markdown variants

In addition to pandoc’s extended Markdown, the following Markdown variants are supported:

markdown_phpextra (PHP Markdown Extra)
footnotes, pipe_tables, raw_html, markdown_attribute, fenced_code_blocks, definition_lists, intraword_underscores, header_attributes, link_attributes, abbreviations, shortcut_reference_links, spaced_reference_links.

markdown_github (deprecated GitHub-Flavored Markdown)
pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris, space_in_atx_header, intraword_underscores, strikeout, task_lists, emoji, shortcut_reference_links, angle_brackets_escapable, lists_without_preceding_blankline.

markdown_mmd (MultiMarkdown)
pipe_tables, raw_html, markdown_attribute, mmd_link_attributes, tex_math_double_backslash, intraword_underscores, mmd_title_block, footnotes, definition_lists, all_symbols_escapable, implicit_header_references, auto_identifiers, mmd_header_identifiers, shortcut_reference_links, implicit_figures, superscript, subscript, backtick_code_blocks, spaced_reference_links, raw_attribute.

markdown_strict (Markdown.pl)
raw_html, shortcut_reference_links, spaced_reference_links.

We also support commonmark and gfm (GitHub-Flavored Markdown, which is implemented as a set of extensions on commonmark).

Note, however, that commonmark and gfm have limited support for extensions. Only those listed below (and smart, raw_tex, and hard_line_breaks) will work. The extensions can, however, all be individually disabled. Also, raw_tex only affects gfm output, not input.

gfm (GitHub-Flavored Markdown)
pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris, space_in_atx_header, intraword_underscores, strikeout, task_lists, emoji, shortcut_reference_links, angle_brackets_escapable, lists_without_preceding_blankline.

Producing slide shows with pandoc

You can use pandoc to produce an HTML + JavaScript slide presentation that can be viewed via a web browser. There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also produce a PDF slide show using LaTeX beamer, or slides shows in Microsoft PowerPoint format.

Here’s the Markdown source for a simple slide show, habits.txt:

% Habits
% John Doe
% March 22, 2005

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

------------------

![picture of spaghetti](images/spaghetti.jpg)

## Going to sleep

- Get in bed
- Count sheep

To produce an HTML/JavaScript slide show, simply type

pandoc -t FORMAT -s habits.txt -o habits.html

where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.

For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the -s/--standalone option embeds a link to JavaScript and CSS files, which are assumed to be available at the relative path s5/default (for S5), slideous (for Slideous), reveal.js (for reveal.js), or at the Slidy website at w3.org (for Slidy). (These paths can be changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url variables; see Variables for HTML slides, above.) For DZSlides, the (relatively short) JavaScript and CSS are included in the file by default.

With all HTML slide formats, the --self-contained option can be used to produce a single file that contains all of the data necessary to display the slide show, including linked scripts, stylesheets, images, and videos.

To produce a PDF slide show using beamer, type

pandoc -t beamer habits.txt -o habits.pdf

Note that a reveal.js slide show can also be converted to a PDF by printing it to a file from the browser.

To produce a Powerpoint slide show, type

pandoc habits.txt -o habits.pptx

Structuring the slide show

Par défaut, le niveau de la diapositive est le niveau de titre le plus élevé dans la hiérarchie qui est suivi immédiatement par le contenu, et non par un autre titre, quelque part dans le document. Dans l'exemple ci-dessus, les titres de niveau 1 sont toujours suivis par des titres de niveau 2, qui sont suivis par le contenu, de sorte que le niveau de la diapositive est de 2. Ce mode de fonctionnement peut être inhibé en utilisant l'option --slide-level.

Le document est découpé en diapositives selon les règles suivantes :

  • Une règle horizontale lance toujours une nouvelle diapositive.

  • Un titre au niveau de la diapositive commence toujours une nouvelle diapositive.

  • Les titres en dessous du niveau de la diapositive dans la hiérarchie créent des titres à l'intérieur d'une diapositive.

  • Les titres au-dessus du niveau de la diapositive dans la hiérarchie créent des "diapositives de titre", qui contiennent simplement le titre de la section et aident à diviser le diaporama en sections. Le contenu qui ne figure pas sous ces rubriques sera inclus sur la diapositive titre (pour les diaporamas HTML) ou sur une diapositive suivante portant le même titre (pour les projecteurs).

  • Une page de titre est construite automatiquement à partir du bloc titre du document, s'il existe. (Dans le cas de beamer, cela peut être désactivé en commentant certaines lignes du modèle par défaut).

Ces règles sont conçues pour prendre en charge de nombreux styles différents de diaporama. Si vous ne vous souciez pas de structurer vos diapositives en sections et sous-sections, vous pouvez simplement utiliser des titres de niveau 1 pour toutes les diapositives. (Dans ce cas, le niveau 1 sera le niveau des diapositives.) Mais vous pouvez également structurer le diaporama en sections, comme dans l'exemple ci-dessus.

Note : dans les diaporamas de reveal.js, si le niveau de la diapositive est 2, une mise en page bidimensionnelle sera produite, les titres de niveau 1 se développant horizontalement et les titres de niveau 2 se développant verticalement. Il n'est pas recommandé d'utiliser un emboîtement plus profond des niveaux de section avec reveal.js.

Incremental lists

Par défaut, ces auteurs produisent des listes qui affichent "tout en même temps". Si vous souhaitez que vos listes s'affichent de manière progressive (un élément à la fois), utilisez l'option -i. Si vous voulez qu'une liste particulière s'écarte de la valeur par défaut, mettez-la dans un bloc div avec classe incremental ou nonincremental. Ainsi, par exemple, en utilisant la syntaxe fenced div, ce qui suit serait incrémentiel indépendamment de la valeur par défaut du document :

::: incremental

- Eat spaghetti
- Drink wine

:::

or

::: nonincremental

- Eat spaghetti
- Drink wine

:::

Bien que l'utilisation de divs incrementalet  nonincremental soit la méthode recommandée pour établir des listes incrémentielles au cas par cas, une méthode plus ancienne est également prise en charge : le fait de mettre des listes à l'intérieur d'un bloc de guillemets s'écartera de la valeur par défaut du document (c'est-à-dire qu'il s'affichera de manière incrémentielle sans l'option -iet tout à la fois avec l'option -i) :

> - Eat spaghetti
> - Drink wine

Les deux méthodes permettent de mélanger des listes incrémentielles et non incrémentielles dans un seul document.

Remarque : ni l'optionni aucune des méthodes décrites ici ne fonctionne actuellement pour la sortie PowerPoint. -i/--incremental option nor any of the methods described here currently works for PowerPoint output.

Inserting pauses

Vous pouvez ajouter des "pauses" à l'intérieur d'une diapositive en incluant un paragraphe contenant trois points, séparés par des espaces :

# Slide with a pause

content before the pause

. . .

content after the pause

Note : cette fonctionnalité n'est pas encore implémentée pour les sorties PowerPoint.

Styling the slides

Vous pouvez modifier le style des diapositives HTML en mettant des fichiers CSS personnalisés dans $DATADIR/s5/default (pour S5), $DATADIR/slidy (pour Slidy), ou $DATADIR/slideous (pour Slideous), où $DATADIR est le répertoire des données de l'utilisateur (voir --data-dir, ci-dessus). Les originaux peuvent être trouvés dans le répertoire des données du système de pandoc (généralement $CABALDIR/pandoc-VERSION/s5/defaultPandoc y recherchera les fichiers qu'il ne trouve pas dans le répertoire des données de l'utilisateur). .

Pour les dzslides, le CSS est inclus dans le fichier HTML lui-même, et peut y être modifié.

Toutes les reveal.js configuration options peuvent être fixées par des variables. Par exemple, les thèmes peuvent être utilisés en définissant la variable theme:

-V theme=moon

Ou vous pouvez spécifier une feuille de style personnalisée en utilisant l'option --css.

Pour styliser les diapositives de beamer, vous pouvez spécifier un theme, colortheme, fonttheme, innertheme, et outertheme, en utilisant l'option -V:

pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

Notez que les attributs d'en-tête se transforment en attributs de diapositive (sur un <div> ou <section>) dans les formats de diapositive HTML, ce qui vous permet de styliser des diapositives individuelles. Dans beamer, le seul attribut de titre qui affecte les diapositives est la classe allowframebreaksqui définit l'option  allowframebreaks, entraînant la création de plusieurs diapositives si le contenu dépasse le cadre. Ceci est particulièrement recommandé pour les bibliographies :

# References {.allowframebreaks}

Speaker notes

Les notes des intervenants sont prises en charge dans reveal.js et la sortie PowerPoint (pptx). Vous pouvez ainsi ajouter des notes à votre document Markdown :

::: notes

This is my note.

- It can contain Markdown
- like this list

:::

Pour afficher la fenêtre des notes dans reveal.js, appuyez sur s pendant la présentation. Les notes des orateurs en PowerPoint seront disponibles, comme d'habitude, sous forme de documents à distribuer et de présentation.

Les notes ne sont pas encore prises en charge pour les autres formats de diapositives, mais les notes n'apparaîtront pas sur les diapositives elles-mêmes.

Columns

Pour placer des documents dans des colonnes côte à côte, vous pouvez utiliser un conteneur div natif avec la classe columns, contenant deux ou plusieurs conteneurs div avec la classe column et un attribut width :

:::::::::::::: {.columns}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

Frame attributes in beamer

Il est parfois nécessaire d'ajouter l'option LaTeX [fragile] à un cadre dans beamer (par exemple, lors de l'utilisation de l'environnement minted environment). On peut y parvenir en ajoutant la classe fragile au titre introduisant la diapositive :

# Fragile slide {.fragile}

Tous les autres attributs de frame décrits dans la section 8.1 du guide de l'utilisateur du Beamer peuvent également être utilisés : allowdisplaybreaks, allowframebreaks, b, c, t, environment, label, plain, shrink, standout, noframenumbering.

Background in reveal.js and beamer

Background images can be added to self-contained reveal.js slideshows and to beamer slideshows.

For the same image on every slide, use the configuration option background-image either in the YAML metadata block or as a command-line variable. (There are no other options in beamer and the rest of this section concerns reveal.js slideshows.)

For reveal.js, you can instead use the reveal.js-native option parallaxBackgroundImage. You can also set parallaxBackgroundHorizontal and parallaxBackgroundVertical the same way and must also set parallaxBackgroundSize to have your values take effect.

To set an image for a particular reveal.js slide, add {data-background-image="/path/to/image"} to the first slide-level heading on the slide (which may even be empty).

In reveal.js’s overview mode, the parallaxBackgroundImage will show up only on the first slide.

Other reveal.js background settings also work on individual slides, including data-background-size, data-background-repeat, data-background-color, data-transition, and data-transition-speed.

To add a background image to the automatically generated title slide, use the title-slide-attributes variable in the YAML metadata block. It must contain a map of attribute names and values.

See the reveal.js documentation for more details.

For example in reveal.js:

---
title: My Slideshow
parallaxBackgroundImage: /path/to/my/background_image.png
title-slide-attributes:
    data-background-image: /path/to/title_image.png
    data-background-size: contain
---

## Slide One

Slide 1 has background_image.png as its background.

## {data-background-image="/path/to/special_image.jpg"}

Slide 2 has a special image for its background, even though the heading has no content.

Creating EPUBs with pandoc

EPUB Metadata

EPUB metadata may be specified using the --epub-metadata option, but if the source document is Markdown, it is better to use a YAML metadata block. Here is an example:

---
title:
- type: main
  text: My Book
- type: subtitle
  text: An investigation of metadata
creator:
- role: author
  text: John Smith
- role: editor
  text: Sarah Jones
identifier:
- scheme: DOI
  text: doi:10.234234.234/33
publisher:  My Press
rights: © 2007 John Smith, CC BY-NC
ibooks:
  version: 1.3.4
...

The following fields are recognized:

identifier
Either a string value or an object with fields text and scheme. Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC.

title
Either a string value, or an object with fields file-as and type, or a list of such objects. Valid values for type are main, subtitle, short, collection, edition, extended.

creator
Either a string value, or an object with fields role, file-as, and text, or a list of such objects. Valid values for role are MARC relators, but pandoc will attempt to translate the human-readable versions (like “author” and “editor”) to the appropriate marc relators.

contributor
Same format as creator.

date
A string value in YYYY-MM-DD format. (Only the year is necessary.) Pandoc will attempt to convert other common date formats.

lang (or legacy: language)
A string value in BCP 47 format. Pandoc will default to the local language if nothing is specified.

subject
A string value or a list of such values.

description
A string value.

type
A string value.

format
A string value.

relation
A string value.

coverage
A string value.

rights
A string value.

cover-image
A string value (path to cover image).

css (or legacy: stylesheet)
A string value (path to CSS stylesheet).

page-progression-direction
Either ltr or rtl. Specifies the page-progression-direction attribute for the spine element.

ibooks
iBooks-specific metadata, with the following fields:

  • version: (string)
  • specified-fonts: true|false (default false)
  • ipad-orientation-lock: portrait-only|landscape-only
  • iphone-orientation-lock: portrait-only|landscape-only
  • binding: true|false (default true)
  • scroll-axis: vertical|horizontal|default

The epub:type attribute

For epub3 output, you can mark up the heading that corresponds to an EPUB chapter using the epub:type attribute. For example, to set the attribute to the value prologue, use this markdown:

# My chapter {epub:type=prologue}

Which will result in:

<body epub:type="frontmatter">
  <section epub:type="prologue">
    <h1>My chapter</h1>

Pandoc will output <body epub:type="bodymatter">, unless you use one of the following values, in which case either frontmatter or backmatter will be output.

epub:type of first section epub:type of body
prologue frontmatter
abstract frontmatter
acknowledgments frontmatter
copyright-page frontmatter
dedication frontmatter
credits frontmatter
keywords frontmatter
imprint frontmatter
contributors frontmatter
other-credits frontmatter
errata frontmatter
revision-history frontmatter
titlepage frontmatter
halftitlepage frontmatter
seriespage frontmatter
foreword frontmatter
preface frontmatter
seriespage frontmatter
titlepage frontmatter
appendix backmatter
colophon backmatter
bibliography backmatter
index backmatter

Linked media

Par défaut, pandoc téléchargera les médias référencés à partir de tout élément <img>, <audio>, <video> ou <source>présent dans l'EPUB généré, et les inclura dans le conteneur EPUB, ce qui donnera un EPUB complètement autonome. Si vous souhaitez plutôt créer des liens vers des ressources médiatiques externes, utilisez du HTML brut dans votre source et ajoutez  data-external="1" à la balise avec l'attribut srcPar exemple:

<audio controls="1">
  <source src="https://example.com/music/toccata.mp3"
          data-external="1" type="audio/mpeg">
  </source>
</audio>

Creating Jupyter notebooks with pandoc

When creating a Jupyter notebook, pandoc will try to infer the notebook structure. Code blocks with the class code will be taken as code cells, and intervening content will be taken as Markdown cells. Attachments will automatically be created for images in Markdown cells. Metadata will be taken from the jupyter metadata field. For example:

---
title: My notebook
jupyter:
  nbformat: 4
  nbformat_minor: 5
  kernelspec:
     display_name: Python 2
     language: python
     name: python2
  language_info:
     codemirror_mode:
       name: ipython
       version: 2
     file_extension: ".py"
     mimetype: "text/x-python"
     name: "python"
     nbconvert_exporter: "python"
     pygments_lexer: "ipython2"
     version: "2.7.15"
---

# Lorem ipsum

**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
bibendum felis dictum sodales.

``` code
print("hello")
```

## Pyout

``` code
from IPython.display import HTML
HTML("""
<script>
console.log("hello");
</script>
<b>HTML</b>
""")
```

## Image

This image ![image](myimage.png) will be
included as a cell attachment.

If you want to add cell attributes, group cells differently, or add output to code cells, then you need to include divs to indicate the structure. You can use either fenced divs or native divs for this. Here is an example:

:::::: {.cell .markdown}
# Lorem

**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
bibendum felis dictum sodales.
::::::

:::::: {.cell .code execution_count=1}
``` {.python}
print("hello")
```

::: {.output .stream .stdout}
```
hello
```
:::
::::::

:::::: {.cell .code execution_count=2}
``` {.python}
from IPython.display import HTML
HTML("""
<script>
console.log("hello");
</script>
<b>HTML</b>
""")
```

::: {.output .execute_result execution_count=2}
```{=html}
<script>
console.log("hello");
</script>
<b>HTML</b>
hello
```
:::
::::::

If you include raw HTML or TeX in an output cell, use the [raw attribute][Extension: fenced_attribute], as shown in the last cell of the example above. Although pandoc can process “bare” raw HTML and TeX, the result is often interspersed raw elements and normal textual elements, and in an output cell pandoc expects a single, connected raw block. To avoid using raw HTML or TeX except when marked explicitly using raw attributes, we recommend specifying the extensions -raw_html-raw_tex+raw_attribute when translating between Markdown and ipynb notebooks.

Note that options and extensions that affect reading and writing of Markdown will also affect Markdown cells in ipynb notebooks. For example, --wrap=preserve will preserve soft line breaks in Markdown cells; --atx-headers will cause ATX-style headings to be used; and --preserve-tabs will prevent tabs from being turned to spaces.

Syntax highlighting

Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name. The Haskell library skylighting is used for highlighting. Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language names that pandoc will recognize, type pandoc --list-highlight-languages.

The color scheme can be selected using the --highlight-style option. The default color scheme is pygments, which imitates the default color scheme used by the Python library pygments (though pygments is not actually used to do the highlighting). To see a list of highlight styles, type pandoc --list-highlight-styles.

If you are not satisfied with the predefined styles, you can use --print-highlight-style to generate a JSON .theme file which can be modified and used as the argument to --highlight-style. To get a JSON version of the pygments style, for example:

pandoc --print-highlight-style pygments > my.theme

Then edit my.theme and use it like this:

pandoc --highlight-style my.theme

If you are not satisfied with the built-in highlighting, or you want highlight a language that isn’t supported, you can use the --syntax-definition option to load a KDE-style XML syntax definition file. Before writing your own, have a look at KDE’s repository of syntax definitions.

To disable highlighting, use the --no-highlight option.

Custom Styles

Custom styles can be used in the docx and ICML formats.

Output

By default, pandoc’s docx and ICML output applies a predefined set of styles for blocks such as paragraphs and block quotes, and uses largely default formatting (italics, bold) for inlines. This will work for most purposes, especially alongside a reference.docx file. However, if you need to apply your own styles to blocks, or match a preexisting set of styles, pandoc allows you to define custom styles for blocks and text using divs and spans, respectively.

If you define a div or span with the attribute custom-style, pandoc will apply your specified style to the contained elements (with the exception of elements whose function depends on a style, like headings, code blocks, block quotes, or links). So, for example, using the bracketed_spans syntax,

[Get out]{custom-style="Emphatically"}, he said.

would produce a docx file with “Get out” styled with character style Emphatically. Similarly, using the fenced_divs syntax,

Dickinson starts the poem simply:

::: {custom-style="Poetry"}
| A Bird came down the Walk---
| He did not know I saw---
:::

would style the two contained lines with the Poetry paragraph style.

For docx output, styles will be defined in the output file as inheriting from normal text, if the styles are not yet in your reference.docx. If they are already defined, pandoc will not alter the definition.

This feature allows for greatest customization in conjunction with pandoc filters. If you want all paragraphs after block quotes to be indented, you can write a filter to apply the styles necessary. If you want all italics to be transformed to the Emphasis character style (perhaps to change their color), you can write a filter which will transform all italicized inlines to inlines within an Emphasis custom-style span.

For docx output, you don’t need to enable any extensions for custom styles to work.

Input

The docx reader, by default, only reads those styles that it can convert into pandoc elements, either by direct conversion or interpreting the derivation of the input document’s styles.

By enabling the styles extension in the docx reader (-f docx+styles), you can produce output that maintains the styles of the input document, using the custom-style class. Paragraph styles are interpreted as divs, while character styles are interpreted as spans.

For example, using the custom-style-reference.docx file in the test directory, we have the following different outputs:

Without the +styles extension:

$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
This is some text.

This is text with an *emphasized* text style. And this is text with a
**strengthened** text style.

> Here is a styled paragraph that inherits from Block Text.

And with the extension:

$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown

::: {custom-style="First Paragraph"}
This is some text.
:::

::: {custom-style="Body Text"}
This is text with an [emphasized]{custom-style="Emphatic"} text style.
And this is text with a [strengthened]{custom-style="Strengthened"}
text style.
:::

::: {custom-style="My Block Style"}
> Here is a styled paragraph that inherits from Block Text.
:::

With these custom styles, you can use your input document as a reference-doc while creating docx output (see below), and maintain the same styles in your input and output files.

Custom writers

Pandoc peut être étendu avec des auteurs personnalisés écrits en Lua. (Pandoc comprend un interprète Lua, il n'est donc pas nécessaire d'installer Lua séparément)

Pour utiliser un auteur personnalisé, il suffit de spécifier le chemin d'accès au script Lua à la place du format de sortie. Par exemple :

pandoc -t data/sample.lua

Pour créer un auteur personnalisé, il faut écrire une fonction Lua pour chaque élément possible d'un document pandoc. Pour obtenir un exemple documenté que vous pouvez modifier en fonction de vos besoins, faites

pandoc --print-default-data-file sample.lua

Notez que les auteurs d'articles personnalisés n'ont pas de modèle par défaut. Si vous souhaitez utiliser --standalone avec un auteur personnalisé, vous devrez spécifier un modèle manuellement en utilisant --template ou ajouter un nouveau modèle par défaut avec le nom default.NAME_OF_CUSTOM_WRITER.lua au sous-répertoire templates de votre répertoire de données utilisateur (voir Templates).

A note on security

If you use pandoc to convert user-contributed content in a web application, here are some things to keep in mind:

  1. Although pandoc itself will not create or modify any files other than those you explicitly ask it create (with the exception of temporary files used in producing PDFs), a filter or custom writer could in principle do anything on your file system. Please audit filters and custom writers very carefully before using them.

  2. If your application uses pandoc as a Haskell library (rather than shelling out to the executable), it is possible to use it in a mode that fully isolates pandoc from your file system, by running the pandoc operations in the PandocPure monad. See the document Using the pandoc API for more details.

  3. Pandoc’s parsers can exhibit pathological performance on some corner cases. It is wise to put any pandoc operations under a timeout, to avoid DOS attacks that exploit these issues. If you are using the pandoc executable, you can add the command line options +RTS -M512M -RTS (for example) to limit the heap size to 512MB.

  4. The HTML generated by pandoc is not guaranteed to be safe. If raw_html is enabled for the Markdown input, users can inject arbitrary HTML. Even if raw_html is disabled, users can include dangerous content in attributes for headings, spans, and code blocks. To be safe, you should run all the generated HTML through an HTML sanitizer.

Authors

Copyright 2006–2020 John MacFarlane ([email protected]). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) For a full list of contributors, see the file AUTHORS.md in the pandoc source code.

  1. The point of this rule is to ensure that normal paragraphs starting with people’s initials, like

    B. Russell was an English philosopher.

    do not get treated as list items.

    This rule will not prevent

    (C) 2007 Joe Smith

    from being interpreted as a list item. In this case, a backslash escape can be used:

    (C\) 2007 Joe Smith

    ↩︎

  2. I have been influenced by the suggestions of David Wheeler.↩︎

  3. This scheme is due to Michel Fortin, who proposed it on the Markdown discussion list.↩︎

  4. To see why laziness is incompatible with relaxing the requirement of a blank line between items, consider the following example:

    bar
:    definition
foo
:    definition

    Is this a single list item with two definitions of “bar,” the first of which is lazily wrapped, or two list items? To remove the ambiguity we must either disallow lazy wrapping or require a blank line between list items.↩︎

⚠️ **GitHub.com Fallback** ⚠️