mdBook : Markdown : Blocs de codes

Le caractère ` est obtenu avec la combinaison de touches AltGr + 7 dans Linux.

Pour insérer un bloc de code, le langage Markdown propose d’utiliser ``` pour identifier le début et la fin du bloc de code.

Les délimiteurs sont placés sur la ligne au-dessus et la ligne en dessous du contenu du bloc de code.

Par exemple :

```
# Ceci est un bloc de code
```

affiche :

# Ceci est un bloc de code

Nous pouvons indiquer le langage utilisé dans le bloc de code (pour la mise en relief des éléments syntaxiques, réalisée par highlight.js).

C’est le cas ici :

```rust
# fn main() {
# use log::{debug, trace, warn};
# use serde::{Deserialize, Deserializer, Serialize, Serializer};
# use std::collections::HashMap;
# use std::env;
# use std::fs::File;
# use std::io::Read;
# use std::path::{Path, PathBuf};
# use std::str::FromStr;
# use toml::value::Table;
# use toml::{self, Value};
#
# use crate::errors::*;
# use crate::utils::{self, toml_ext::TomlExt};
#
/// The overall configuration object for MDBook, essentially an in-memory
/// representation of `book.toml`.
#[derive(Debug, Clone, PartialEq)]
pub struct Config {
    /// Metadata about the book.
    pub book: BookConfig,
    /// Information about the build environment.
    pub build: BuildConfig,
    /// Information about Rust language support.
    pub rust: RustConfig,
    rest: Value,
}
# }
```

qui affiche :

fn main() {
use log::{debug, trace, warn};
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use std::collections::HashMap;
use std::env;
use std::fs::File;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use toml::value::Table;
use toml::{self, Value};

use crate::errors::*;
use crate::utils::{self, toml_ext::TomlExt};

/// The overall configuration object for MDBook, essentially an in-memory
/// representation of `book.toml`.
#[derive(Debug, Clone, PartialEq)]
pub struct Config {
    /// Metadata about the book.
    pub book: BookConfig,
    /// Information about the build environment.
    pub build: BuildConfig,
    /// Information about Rust language support.
    pub rust: RustConfig,
    rest: Value,
}
}

(Il s’agit d’un extrait du fichier config.rs du code source de mdBook).

Fonctions associées aux blocs de code

Comme vous pouvez vous en apercevoir en passant la souris au dessus du bloc de code ci-avant, les blocs de code bénéficient de fonctions particulières, comme la fonction pour copier le contenu du bloc dans le presse-papiers.

Exclusivités Rust

Les codes Rust bénéficient de fonctions supplémentaires pour les tester dans un outil mis à disposition de la communauté :

• le « Run this code » pour compiler le code puis (éventuellement) l’exécuter, via un outil de la communauté Rust, directement dans la page : très intéressant pour réaliser des documentations et tutoriels Rust donc ! ;

D’autres fonctions avancées sont possibles moyennant quelques options comme :

• la modification du code par l’internaute directement dans le bloc de code ;
• la numérotation automatique des lignes ainsi que
• le masquage de parties du code ;
• etc.

Position des ```

Note : je vous ai indiqué de disposer les ``` au dessus et en dessous du contenu car nous cherchons à afficher un bloc de code.

Il est possible d’utiliser les ``` dans la même ligne pour affiche un code dans un paragraphe (et non un bloc de code).

Par exemple :

J'ai envie d'écrire ```Ceci est un code``` et je le fais.

affiche :

J’ai envie d’écrire Ceci est un code et je le fais.

Nombre de `

Comme nous avons vu qu’il est possible de doubler le ` dans le cas de l’insertion d’un code dans un paragraphe, nous pouvons en ajouter un quatrième pour encadrer un bloc de code dans lequel nous souhaitons afficher ```.

Par exemple :

````
```
Ceci est un code
```
````

Affiche :

```
Ceci est un code
```

Ou encore :

J'ai envie d'écrire ```` ``` ````.

affiche :

J’ai envie d’écrire ```.

Il suffit de se souvenir d’ajouter une espace pour aider le compilateur à détecter et comprendre notre besoin. En principe, les espaces ne sont pas traités dans les blocs de code. Ces applications démontrent qu’il est bon, parfois, de prévoir des exceptions à la règle.

Alternative Markdown : la tabulation

Nous pouvons utiliser une tabulation pour indiquer qu’un texte est un bloc de code.

Par exemple

	Ceci est un code

affiche :

Ceci est un code

Je recommande d’utiliser la notation explicite avec les ``` avant et après le texte car c’est la méthode décrite dans la documentation mdBook officielle et que c’est la méthode la plus lisible, sûre, et extensible.