# Rédiger en Markdown

Rédigez avec le Markdown que vous connaissez et produisez un PDF ou un document modifiable pour vos collaborateurs.

Le Markdown convient bien aux notes de recherche, aux rapports et aux premiers brouillons. Oleafly lui offre une barre de mise en forme dédiée et un chemin de compilation Pandoc, avec des fichiers source que vous pouvez utiliser hors de l'application.

## Créez un rapport

1. Choisissez **Nouveau projet → Utiliser un modèle → Blank Markdown document**.
2. Nommez le projet **Notes de terrain** et ouvrez `main.md`.
3. Collez cet exemple, puis choisissez **Recompiler** ou appuyez sur **⌘Enter / Ctrl+Enter**.
4. Si Oleafly propose d'installer un moteur nécessaire, terminez cette installation et compilez à nouveau.

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

Le PDF doit comprendre un titre, des titres de section, une liste numérotée et un tableau. Les métadonnées entre la première paire de lignes `---` contrôlent le titre et l'auteur du document.

## Types de document

Ajoutez une ligne `type` à l'en-tête (front matter) pour produire le document comme un rapport, un livre, des diapositives, un poster, une lettre ou un CV. Sans `type`, ou avec une valeur qu'Oleafly ne connaît pas, le document est produit comme un article.

| `type` | Ce qu'il produit | Rempli sauf si vous le définissez |
| --- | --- | --- |
| `article` | Un article | Rien |
| `report` ou `thesis` | Un rapport, avec un chapitre à chaque titre `#` | `documentclass: report` |
| `book` | Un livre, avec un chapitre à chaque titre `#` | `documentclass: book` |
| `slides` | Des diapositives Beamer 16:9. Un titre `#` ouvre une section et un titre `##` ouvre une diapositive | `aspectratio: 169` |
| `poster` | Un poster Beamer d'une page, coiffé de son `title`, `subtitle`, `author` et `institute` | Papier A0, en portrait |
| `letter` | Une lettre avec votre adresse et celle du destinataire, un objet, une formule d'appel et une formule de politesse | `documentclass: scrlttr2` |
| `cv` | Un article compact | `geometry: margin=2cm` et `pagestyle: empty` |

Votre propre en-tête garde le dernier mot. Une valeur que vous définissez vous-même, comme `documentclass`, `aspectratio` ou `geometry`, remplace celle que le type remplit.

Pour des diapositives, définissez `slide-level` pour choisir le niveau de titre qui ouvre une diapositive. Avec `slide-level: 1`, chaque titre `#` en ouvre une. Les diapositives sont produites comme un PDF ordinaire : **Présenter** dans la barre d'outils de l'aperçu peut donc les afficher. Voir [Présenter des diapositives](/docs/present-slides/).

Un poster est en A0 sauf si vous définissez `papersize` sur `a1`, `a2`, `a3` ou `a4`. Les autres formats, comme `letter` ou `a5`, sont ignorés. Ajoutez `orientation: landscape` pour un poster en largeur.

Une lettre prend l'adresse du destinataire dans `to` et la vôtre dans `from`. `opening` est la formule d'appel, et `closing` est la ligne avant votre nom, qui vient de `author`. `subject` devient l'objet, ou `title` s'il n'y a pas de `subject`. Écrivez une adresse sous forme de liste, une ligne par élément.

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

**Type de document** dans les [Réglages du document](/docs/document-settings/#markdown) écrit la ligne `type` pour vous. Un [export LaTeX](/docs/export/#what-each-format-keeps) suit aussi le type, et un [export PowerPoint](/docs/export/#presentation-and-book-exports) de diapositives utilise le même `slide-level`. [`oleafly build`](/docs/cli/#build-a-project) produit chaque type comme le fait l'application.

## Édition source et visuelle

Le commutateur au début de la barre d'outils a trois modes. **Code** modifie le Markdown directement. **Visuel** offre une édition mise en forme pour les titres, les paragraphes, les listes, les liens, les images et les tableaux. Le mode **Les deux** affiche le source et le texte mis en forme ensemble. Ouvrez son menu pour choisir **Empilé** ou **Fractionner**. Les nouveaux projets s'ouvrent en mode Code, et chaque projet retient le mode dans lequel vous l'avez laissé.

Souligné, surlignage, exposant et indice sont des contrôles de mise en forme Pandoc en mode Code. Leurs boutons sont masqués en mode Visuel. Utilisez Code pour travailler avec les métadonnées, la syntaxe de citation ou d'autres constructions du source.

[Télécharger le source de l'exemple](/examples/writing-example.md)

## Chaque outil de la barre d'outils

Sélectionnez du texte avant de cliquer sur un contrôle de mise en forme. En mode Code, la plupart des outils entourent la sélection ou insèrent un espace réservé. Ouvrez **Plus d'options de mise en forme** (`…`) pour atteindre les contrôles qui ne tiennent pas dans la barre.

### Code / Visuel

Basculez entre **Code**, **Visuel** et **Les deux**. Le document reste du source Markdown dans tous les modes.

### Annuler

Annule la dernière modification. ⌘Z / Ctrl+Z.

### Rétablir

Rétablit une modification annulée. **⌘Shift+Z / Ctrl+Shift+Z**.

### Titre → Titre

Choisissez **Titre** dans le menu des titres pour insérer `# Title`. Remplacez le texte du titre par votre propre titre.

### Titre → Section

Choisissez **Section** dans le menu des titres pour insérer `## Section`. Remplacez le texte du titre par votre propre titre.

### Titre → Sous-section

Choisissez **Sous-section** dans le menu des titres pour insérer `### Subsection`. Remplacez le texte du titre par votre propre titre.

### Titre → Sous-sous-section

Choisissez **Sous-sous-section** dans le menu des titres pour insérer `#### Subsubsection`. Remplacez le texte du titre par votre propre titre.

### Titre → Titre mineur

Choisissez **Titre mineur** dans le menu des titres pour insérer `##### Minor heading`. Remplacez le texte du titre par votre propre titre.

### Titre → Titre de paragraphe

Choisissez **Titre de paragraphe** dans le menu des titres pour insérer `###### Paragraph heading`. Remplacez le texte du titre par votre propre titre.

### Liste à puces

Démarre une liste non ordonnée. `- Item`.

### Liste numérotée

Démarre une séquence. `1. Item`.

### Liste de tâches

En mode Code, ajoutez une tâche et changez `[ ]` en `[x]` une fois faite. `- [ ] Task`.

### Citation en bloc

Placez une citation sur sa propre ligne. `> quoted text`.

### Gras

Met le texte sélectionné en valeur. `**text**` ; ⌘B / Ctrl+B.

### Italique

Met un terme en valeur. `*text*` ; ⌘I / Ctrl+I.

### Barré

Marque un texte comme remplacé. `~~text~~`.

### Code en ligne

Met en forme un nom de fichier, une commande ou un identifiant. Du texte encadré par des accents graves.

### Souligné

Sélectionnez une expression en mode Code. `[text]{.underline}`.

### Surlignage

Sélectionnez une expression en mode Code. `[text]{.mark}`.

### Exposant

Sélectionnez l'exposant en mode Code. `^text^`.

### Indice

Sélectionnez l'indice en mode Code. `~text~`.

Souligné et surlignage utilisent des attributs Pandoc pour que la mise en forme survive jusqu'au PDF. Utilisez ces contrôles plutôt que d'ajouter des balises HTML brutes au manuscrit.

### Insérer un lien

En mode **Code** : insère `[link text](url)`. Remplacez les deux espaces réservés.

En mode **Visuel** : ouvre **URL du lien**. Saisissez l'adresse et appliquez-la à votre sélection. Utilisez **Retirer le lien** pour garder le texte sans le lien.

### Insérer une image

En mode **Code** : insère `![caption](image-filename)`. Remplacez le chemin et la légende.

En mode **Visuel** : ouvre **Fichier image**. Saisissez un chemin de projet comme `figures/plot.png` et appliquez-le.

Les images PNG, JPG, PDF, SVG, GIF, WebP et BMP entrent toutes dans le PDF. Oleafly convertit pour vous les SVG, GIF et WebP à la compilation. Les images TIFF, AVIF, HEIC et JPEG XL ne peuvent pas y entrer : la compilation s'arrête et nomme le fichier, alors enregistrez-le dans l'un des autres formats et compilez de nouveau. Si une conversion échoue, vérifiez que l'image s'ouvre, ou enregistrez-la en PNG ou en PDF.

### Insérer un tableau

En mode **Code** : insère trois colonnes, un en-tête et deux lignes de données. Remplacez les noms de colonnes et les cellules.

En mode **Visuel** : insère un tableau modifiable avec les mêmes dimensions de départ.

### Dessiner un diagramme

Ouvre le [compositeur de diagrammes](/docs/figures-diagrams/) en mode Mermaid. Dessinez un organigramme sur le canevas ou modifiez le code Mermaid, puis choisissez **Insérer en Mermaid** pour l'ajouter au curseur sous forme de bloc de code `mermaid` délimité. Voir [Diagrammes Mermaid](#mermaid-diagrams).

### Analyse du document

Liste les titres, figures, tableaux, équations, étiquettes, citations et à faire du document dans l'ordre du source, chacun relié à sa ligne. Elle lit aussi le titre, les auteurs, les mots-clés, la date et le résumé depuis l'en-tête, et peut les copier pour un formulaire de soumission. Voir [Analyse du document](/docs/document-insights/).

### Réglages du document

Change le type de document, la classe de document, la taille de page, les colonnes, les marges, la police de corps, la taille de police, la langue, l'interligne et la numérotation des sections. Oleafly écrit vos choix dans l'en-tête YAML que Pandoc lit, et ajoute un bloc d'en-tête si le fichier n'en a pas. Voir [Réglages du document](/docs/document-settings/#markdown).

### Infos du projet

En mode **Code** : affiche les statistiques du projet et de la sélection.

En mode **Visuel** : affiche les statistiques de la surface d'édition visuelle.

### Rechercher

En mode **Code** : ouvre la recherche du fichier actif avec ⌘F / Ctrl+F.

En mode **Visuel** : le bouton Rechercher de la barre du source est masqué.

Importez l'image dans l'arborescence de fichiers avant d'y faire référence. Gardez les chemins d'images relatifs au manuscrit, pour que l'archive source fonctionne sur un autre ordinateur.

![Un carnet de laboratoire Markdown modifié dans les vues source et visuelle, avec le tableau et la liste de tâches qui restent synchronisés.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## Équations et blocs de code

Écrivez les maths en ligne comme `$x^2$`. Mettez une équation hors ligne entre deux paires de signes dollar :

```markdown
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
```

Pour un exemple de code, encadrez le code de triples accents graves et placez son langage après l'accent ouvrant. Ce sont des constructions du source ; la barre d'outils Markdown n'a pas de bouton séparé pour les équations ni pour les blocs de code délimités.

En mode Visuel, un bloc délimité reste un bloc de code et garde son langage et ses lignes vides, si bien que les diagrammes Mermaid survivent. Saisissez trois accents graves pour démarrer un nouveau bloc, et appuyez sur Tab pour indenter à l'intérieur d'un bloc.

## Diagrammes Mermaid

Choisissez **Dessiner un diagramme** dans la barre d'outils pour créer un organigramme Mermaid dans le compositeur de diagrammes. **Insérer en Mermaid** l'ajoute sous forme de bloc de code délimité :

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

En mode **Les deux**, le côté mis en forme dessine le bloc comme un diagramme. Un PDF a besoin d'une image ; le compositeur enregistre donc aussi un PNG rendu dans `figures/mermaid-<hash>.png`, et la compilation place cette image à la place du bloc. Le diagramme apparaît donc aussi dans le PDF compilé, et dans les exports Word, HTML, EPUB et PowerPoint. Si vous modifiez le bloc à la main ensuite, le PDF affiche le code jusqu'à ce que vous insériez ou enregistriez à nouveau le diagramme depuis le compositeur. Voir [Mermaid dans les documents Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## Texte dans d'autres langues

Oleafly choisit des polices pour les écritures qu'il trouve dans le document : le coréen, le japonais, le chinois, l'arabe, l'hébreu, le grec, le cyrillique, le devanagari, le thaï et plusieurs autres s'affichent donc sans aucune configuration. Les symboles et les emoji reçoivent aussi une police, avec des emoji en noir et blanc. Un document écrit en majorité en arabe ou en hébreu s'affiche de droite à gauche.

Les caractères chinois figurent à la fois dans le texte chinois et dans le texte japonais ; réglez donc `lang` dans l'en-tête YAML pour obtenir la bonne police : `ja` pour le japonais, `zh` pour le chinois simplifié, `zh-TW` pour le chinois traditionnel, ou `ko` pour le coréen. Sans `lang`, Oleafly se fie au texte : les kana indiquent le japonais et les hangul le coréen.

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

Les polices que vous choisissez vous-même passent en premier. Quand l'en-tête YAML définit `mainfont` ou `CJKmainfont`, ou que `header-includes` configure des polices, Oleafly laisse cette partie tranquille.

### Caractères manquants dans le PDF

Quand aucune police utilisée n'a un caractère, le PDF se construit quand même sans lui, et la compilation affiche un avertissement avec un échantillon des caractères manquants. Pour corriger cela :

- Pour du texte coréen, chinois ou japonais, réglez `CJKmainfont` dans l'en-tête YAML sur une police installée sur votre ordinateur qui contient les caractères.
- Pour un autre texte, réglez `mainfont` de la même façon. **Police du texte**, dans les [Réglages du document](/docs/document-settings/#markdown), l'écrit pour vous.
- Pour un symbole rare, utilisez plutôt une image.

## Citations et bibliographie

Importez ou créez `references.bib`, ajoutez `bibliography: references.bib` aux métadonnées YAML, puis citez une clé existante avec `[@citation-key]`. Pandoc utilise la bibliographie pour produire des citations mises en forme et une liste de références.

Si l'en-tête YAML ne nomme aucune bibliographie, ou nomme un fichier qui n'existe pas, la compilation utilise les fichiers `.bib` du projet qui contiennent les clés que vous citez. Une citation sans aucune bibliographie reste dans le PDF telle que vous l'avez saisie, comme `[@smith2020]`, pour que vous puissiez écrire d'abord et ajouter les références plus tard. Un document qui ne cite rien se compile sans lire aucun fichier `.bib`.

[Trouver et gérer les références →](/docs/citations/)

## Import et export

Pour garder un brouillon existant en Markdown, créez un Blank Markdown document, collez le brouillon dans `main.md`, puis importez ses images et sa bibliographie. L'import **Document Markdown**, séparé dans la bibliothèque, convertit pour l'instant un brouillon en LaTeX. [Routes d'importation](/docs/import-project/) explique les deux chemins.

Compilez pour obtenir un PDF, ou utilisez **Exporter** pour créer du Word, du HTML, du Typst, du LaTeX, du PowerPoint, de l'EPUB ou du texte brut. Les exports vers LaTeX et Typst gardent la bibliographie et pointent vers vos fichiers d'images au lieu de les copier : gardez donc ces fichiers à côté de l'export. Quand Pandoc omet quelque chose, l'export est enregistré avec des avertissements, et **Afficher les avertissements** liste ce qui a été abandonné. Utilisez un ZIP de source pour partager le Markdown d'origine et ses ressources. [Exporter votre travail](/docs/export/) couvre la séquence et les vérifications à faire dans le fichier converti.
