> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/fr/articles-approfondis/30-how-to-write-in-markdown-on-overleaf.md).
# Comment écrire en Markdown sur Overleaf
**Mise à jour post-publication** (ajouté le 13 mai 2017) : Nous sommes reconnaissants à Vít Novotný, l'auteur/mainteneur du `markdown` package, de nous avoir écrit avec quelques remarques utiles concernant l'article original. Nous sommes heureux de publier cette version mise à jour qui tient compte de ses conseils et suggestions.
### Hein, quoi ?
[Markdown](https://kirkstrobeck.github.io/whatismarkdown.com/) est un langage de balisage léger (vous voyez ? 😉) qui vous permet de rédiger quelque chose en texte brut avec quelques *très* règles simples, puis de le transformer en sorties formatées, par exemple en HTML. Il est très populaire parmi les développeurs et programmeurs, précisément à cause de sa simplicité (et puis, permettez-moi d'ajouter, il est aussi parfait pour prendre des notes !).
Par exemple, pour écrire une liste de courses rapide :
```
# Liste de courses
*N'oubliez pas* de prendre autant que possible lors des prochaines [soldes](http://acme-marg.com) !
## Nourriture
- haricots cuits au four
- spaghetti
## Papeterie
- bloc-notes
- crayons
```
Et vous obtiendrez en sortie HTML, à l'aide d'un outil tel que [pandoc](http://pandoc.org/):
```html
Liste de courses
N'oubliez pas de prendre autant que possible lors des prochaines soldes !
Nourriture
- haricots cuits au four
- spaghetti
Papeterie
```
C'est simple et agréable ! Vous pouvez trouver d'autres syntaxes pour Markdown [ici](https://daringfireball.net/projects/markdown/syntax).
### Alors, qu'est-ce que cela signifie pour moi ?
De nombreux utilisateurs de LaTeX sont satisfaits de leurs beaux documents composés en LaTeX, mais ne peuvent s'empêcher de ressentir une pointe d'envie envers les utilisateurs de Markdown — parce que, eh bien, le balisage LaTeX *peut* peut parfois devenir assez verbeux. Oui, les listes, on vous regarde *vous*...
La bonne nouvelle, c'est que le formidable nouveau [`markdown` package LaTeX](https://ctan.org/pkg/markdown) vous permet d'écrire une syntaxe markdown dans vos documents LaTeX (c'est-à-dire des entrées plus simples) tout en obtenant malgré tout de magnifiques PDF composés ! Tout ce que vous avez à faire est de charger le `markdown` package dans votre document et d'encadrer votre contenu Markdown dans un `markdown` environnement :
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# Liste de courses
*N'oubliez pas* de prendre autant que possible lors des prochaines [soldes](http://acme-marg.com) !
## Nourriture
- haricots cuits au four
- spaghetti
## Papeterie
- bloc-notes
- crayons
\end{markdown}
\end{document}
```
Ou, si vous préférez mettre votre contenu Markdown dans un `*.md` fichier :
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}
```
Pratique ! Cela rendra très probablement les développeurs très heureux, car ils peuvent désormais simplement copier leur `.md` documentation !
### Puis-je encore utiliser des commandes LaTeX si j'écris en Markdown ?
Oui, vous pouvez toujours utiliser des commandes LaTeX dans votre contenu Markdown ! Il suffit de passer l' `hybrid` option à `markdown`:
```latex
\usepackage[hybrid]{markdown}
...
- bloc-notes (du genre avec le grand $E=mc^2$ sur la couverture)
```
### Comment puis-je utiliser des caractères littéraux comme '#' et '\_' (tirets bas) ?
#### Taper un '#'
Vous ne pouvez pas taper le caractère '#' *dans l' `markdown` environnement*. Pas même `\#` ne fonctionnera. Vous devez définir une commande comme `\newcommand{\texthash}{\#}`, puis utiliser `\texthash` dans votre `markdown` environnement. De même pour les tirets bas, surtout lorsqu'il y en a plus d'un sur la même ligne, par exemple `$y = m_1 + n_2$`. Parfois, il peut être plus simple de terminer l' `markdown` environnement en cours et d'écrire les lignes problématiques en mode LaTeX ordinaire, puis de commencer un autre `markdown` environnement.
#### Taper '\_' (tiret bas) et '\`' (accent grave)
**Mise à jour** (ajouté le 13 mai 2017) : Depuis `markdown` la version 2.5, vous pouvez définir `underscores = false` et `codeSpans = false` pour désactiver les tirets bas et les accents graves. Cela permet d'écrire les indices mathématiques et les guillemets en mode hybride sans les échapper. Nous avons les astérisques pour l'emphase, donc la seule véritable perte concerne les exemples de code en ligne. Merci à Vít pour l'astuce !
#### Environnements à éviter...
Et même si vous pouvez utiliser les accents graves pour écrire du texte verbatim en ligne, ou indenter la ligne avec quatre espaces pour un bloc verbatim, n'utilisez pas `lstlisting` ni `minted` d'environnements LaTeX dans des `markdown` environnements. Il ne faut tout simplement pas.
#### Utiliser du HTML dans un environnement markdown
Et non, vous ne pouvez pas utiliser de HTML à l'intérieur de l' `markdown` environnement LaTeX (même si c'est une chose courante à faire dans le Markdown habituel). Désolé.
**Mise à jour** (ajouté le 13 mai 2017) : À partir de `markdown` la v2.3, il existe une `html` option qui n'affichera pas les balises HTML telles quelles si elles sont présentes dans votre contenu markdown, mais elle ne formatera pas non plus le contenu des balises — c'est-à-dire `Bonjour !` affichera simplement Bonjour ! en graisse normale. Mais les entités HTML comme `©` seront rendues sous la forme ©. Merci à Vít d'avoir signalé cela.
### Options de package markdown suggérées
Un ensemble d' `markdown` options de package que vous pourriez trouver utiles est :
```latex
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
```
Ces options permettent l'utilisation de
* la syntaxe markdown des notes de bas de page (comme `[^1]`);
* les listes de définitions et `#` pour les listes numérotées ;
* des points de suspension « corrects » (…).
Voici un [exemple complet](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) dans la galerie Overleaf, et en voici [un autre](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### Hyperliens et notes de bas de page : comment ?
Dans l'exemple Overleaf, le lien hypertexte est une note de bas de page. Comment faire pour qu'il devienne un hyperlien hyperref ?
`markdown` est personnalisable, donc vous pouvez définir comment vous souhaitez que différents éléments soient rendus. Ajouter cela à votre préambule fera exactement cela :
```latex
\markdownSetup{renderers={
link = {\href{#2}{#1}}
}}
```
**Mise à jour** (ajouté le 13 mai 2017) : `rendererPrototypes` était utilisé dans la version initiale. Il est recommandé aux utilisateurs normaux d'utiliser `renderers` pour leurs propres définitions, car `rendererPrototypes` est destiné aux créateurs de packages pour fournir des valeurs par défaut. Si vous modifiez `rendererPrototypes`, vous risquez qu'un autre package remplace vos paramètres. Merci à Vít d'avoir signalé cela !
### Inclure des images (mise à jour du 8 novembre 2022)
* **Remarque**: L'exemple suivant utilise un fichier graphique (`example-image.pdf`) fourni par le `mwe` package. Ces fichiers graphiques sont distribués par TeX Live et sont donc stockés sur les serveurs d'Overleaf, ce qui les rend disponibles comme espaces réservés d'images, comme dans l'exemple ci-dessous.
Les images peuvent être incluses dans markdown en écrivant le balisage au format suivant :
```latex
```
Espérons que les noms de paramètres `texte alternatif`, `nom de fichier` et `"légende de l'image"` décrivent ce qu'ils font. Voici un exemple pour les illustrer :
```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
% Le package mwe fournit des images d'exemple. Le charger est
% pas essentiel, car ces images se trouvent dans le chemin de recherche de LaTeX.
% Ici, nous le chargeons pour plus de clarté dans cet exemple.
\usepackage{mwe}
\begin{document}
\begin{markdown}
Cet exemple montre comment importer un fichier graphique. Ici, nous utilisons une
image d'exemple fournie par le package `mwe`.
% Utilisez \setkeys{Gin} si vous devez modifier la taille d'affichage d'une image
\setkeys{Gin}{width=.5\linewidth}
\end{markdown}
\end{document}
```
[Ouvrez cet exemple sur Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)
Cet exemple produit le résultat suivant :
#### Remarque sur la largeur de l'image
Comme la plupart des packages, `markdown` charge d'autres packages, y compris [`keyval`](https://ctan.org/pkg/keyval?lang=en) et [`graphicx`](https://ctan.org/pkg/graphicx?lang=en), afin d'utiliser les commandes et fonctionnalités qu'ils fournissent. Ici, la largeur de l'image est définie à l'aide de la `\setkeys` commande, qui est fournie par `keyvals`. `Gin` est une « famille » de clés définie par le `graphicx` package.
* **Remarque**: Comme une commande LaTeX, ici `\setkeys`, est utilisée *dans* le `markdown` l'environnement `hybrid` , l'option du package markdown est requise.
#### Modifier les identifiants de placement des flottants (plus avancé)
La syntaxe markdown pour l'inclusion de figures ne vous permet pas de spécifier directement les identifiants de placement des flottants, mais vous pouvez les ajuster en redéfinissant la façon dont la figure est rendue :
```latex
\markdownSetup{renderers={
image = {\begin{figure}[hbt!]
\centering
\includegraphics{#3}%
\ifx\empty#4\empty\else
\caption{#4}%
\fi
\end{figure}}
}}
```
Pour plus d'informations, consultez la [documentation markdown](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### Pouvez-vous créer des tableaux en utilisant Markdown dans LaTeX ? 😀
Malheureusement, non. Les tableaux ne sont pris en charge que dans [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) seulement, et le package LaTeX `markdown` ne le prend actuellement pas en charge.
**Mise à jour** (ajouté le 13 mai 2017) : D'après une astuce de Vít, il est possible d'utiliser l' `contentBlocks` extension de syntaxe depuis la version 2.4, ou de modifier le `inputFencedCode` renderer, pour convertir rapidement un texte de type CSV en tableau.
### Encore plus de petits plus du package markdown ?
Comme mentionné plus tôt, c'est un moyen sympa de prendre des notes, et lorsqu'il est combiné avec de belles classes de documents LaTeX ou des configurations de packages adaptées, il vous permet d'avoir à la fin d'un cours un beau cahier prêt à l'emploi. Par exemple, vous pourriez l'utiliser avec les [classes Tufte](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}
```
Et la syntaxe courte et simple qui rend l'écriture de listes bien plus pratique signifie que nous avons maintenant un *vraiment rapide* moyen d'écrire des [présentations Beamer](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) et [des affiches](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
Amusez-vous bien !
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/latex/fr/articles-approfondis/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.