Mettre en forme le code

Afficher du code inline et des code blocks

​

Ajouter des exemples de code

Vous pouvez ajouter des extraits de code en ligne ou des code blocks. Les code blocks prennent en charge des options de métadonnées pour la coloration syntaxique, les titles, la mise en évidence de lignes, les icon, et plus encore.

​

Code en ligne

Pour indiquer qu’un mot ou une expression est du code, encadrez-le de backticks (`).

Pour désigner un `mot` ou une `phrase` comme du code, entourez-le de backticks (`).

​

Blocs de code

Utilisez des blocs de code délimités en entourant le code de trois accents graves. Les blocs de code sont copiables et, si vous avez activé l’Assistant, les utilisateurs peuvent demander à l’IA d’expliquer le code.

Indiquez le langage de programmation pour la coloration syntaxique et pour activer les options méta. Ajoutez les options méta, comme un title ou un icon, après le langage.

HelloWorld.java example

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

​

Options de code block

Vous pouvez ajouter des options méta à vos code blocks pour personnaliser leur apparence.

Vous devez spécifier un langage de programmation pour un code block avant d’ajouter toute autre option méta.

​

Syntaxe des options

• Options de type chaîne ou booléen : Entourez-les de "", '' ou laissez sans guillemets.
• Options d’expression : Entourez-les de {}, "" ou ''.

​

Mise en surbrillance de la syntaxe

Activez la coloration syntaxique en indiquant le langage de programmation après les backticks ouvrants d’un code block.

Nous utilisons Shiki pour la coloration syntaxique et prenons en charge tous les langages disponibles. Consultez la liste complète des langages dans la documentation de Shiki.

Personnalisez globalement les thèmes des code blocks avec styling.codeblocks dans votre fichier docs.json. Définissez des thèmes simples comme system ou dark, ou configurez des thèmes Shiki personnalisés pour les modes clair et sombre. Voir Paramètres pour les options de configuration.

Exemple de coloration syntaxique

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

​

Twoslash

Dans les code blocks JavaScript et TypeScript, utilisez twoslash pour afficher des informations de type interactives. Les utilisateurs peuvent survoler les variables, fonctions et paramètres pour voir les types et les erreurs comme dans un IDE.

Twoslash example

type Pet = "cat" | "dog" | "hamster";

function adoptPet(name: string, type: Pet) {
  return `${name} the ${type} is now adopted!`;
}

// Survolez pour voir les types inférés
const message = adoptPet("Mintie", "cat");

​

Titre

Ajoutez un titre pour identifier votre exemple de code. Utilisez title="Your title" ou une chaîne sur une seule ligne.

Exemple de titre

const hello = "world";

​

Icône

Ajoutez une icône à votre code block en utilisant la propriété icon. Consultez Icônes pour voir toutes les options disponibles.

Exemple d’icône

const hello = "world";

​

Mise en surbrillance des lignes

Mettez en surbrillance des lignes spécifiques dans vos code blocks à l’aide de highlight avec les numéros de ligne ou les plages que vous souhaitez mettre en évidence.

Exemple de mise en surbrillance des lignes

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();

​

Mise en évidence de lignes

Mettez en évidence des lignes spécifiques dans vos code blocks à l’aide de focus avec des numéros de ligne ou des plages.

Exemple de mise en évidence de lignes

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();

​

Afficher les numéros de ligne

Affichez les numéros de ligne à gauche de votre code block à l’aide de lines.

Exemple d’affichage des numéros de ligne

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();

​

Repliable

Permettez aux utilisateurs d’ouvrir et de replier de longs code blocks à l’aide de expandable.

Exemple repliable

from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass

@dataclass
class Book:
    title: str
    author: str
    isbn: str
    checked_out: bool = False
    due_date: Optional[datetime] = None

class Library:
    def __init__(self):
        self.books: Dict[str, Book] = {}
        self.checkouts: Dict[str, List[str]] = {}  # abonné -> liste d’ISBN

    def add_book(self, book: Book) -> None:
        if book.isbn in self.books:
            raise ValueError(f"Book with ISBN {book.isbn} already exists")
        self.books[book.isbn] = book

    def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None:
        if patron not in self.checkouts:
            self.checkouts[patron] = []

        book = self.books.get(isbn)
        if not book:
            raise ValueError("Book not found")

        if book.checked_out:
            raise ValueError("Book is already checked out")

        if len(self.checkouts[patron]) >= 3:
            raise ValueError("Patron has reached checkout limit")

        book.checked_out = True
        book.due_date = datetime.now() + timedelta(days=days)
        self.checkouts[patron].append(isbn)

    def return_book(self, isbn: str) -> float:
        book = self.books.get(isbn)
        if not book or not book.checked_out:
            raise ValueError("Book not found or not checked out")

        late_fee = 0.0
        if datetime.now() > book.due_date:
            days_late = (datetime.now() - book.due_date).days
            late_fee = days_late * 0.50

        book.checked_out = False
        book.due_date = None

        # Remove from patron's checkouts
        for patron, books in self.checkouts.items():
            if isbn in books:
                books.remove(isbn)
                break

        return late_fee

    def search(self, query: str) -> List[Book]:
        query = query.lower()
        return [
            book for book in self.books.values()
            if query in book.title.lower() or query in book.author.lower()
        ]

def main():
    library = Library()

    # Ajouter quelques livres
    books = [
        Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"),
        Book("1984", "George Orwell", "978-0-452-28423-4"),
    ]

    for book in books:
        library.add_book(book)

    # Exemple d’emprunt et de retour
    library.checkout_book("978-0-261-10295-4", "patron123")
    late_fee = library.return_book("978-0-261-10295-4")
    print(f"Late fee: ${late_fee:.2f}")

if __name__ == "__main__":
    main()

​

Retour à la ligne

Activez le retour à la ligne pour les lignes longues avec wrap. Cela évite le défilement horizontal et facilite la lecture des lignes longues.

Exemple Wrap

const greeting = "Hello, World! I am a long line of text that will wrap to the next line.";
function sayHello() {
  console.log(greeting);
}
sayHello();

​

Diff

Affichez une comparaison visuelle des lignes ajoutées ou supprimées dans vos code blocks. Les lignes ajoutées sont surlignées en vert et les lignes supprimées sont surlignées en rouge.

Pour créer des diff, ajoutez ces commentaires spéciaux à la fin des lignes dans votre code block :

• // [!code ++] : Marquez une ligne comme ajoutée (surlignage vert).
• // [!code --] : Marquez une ligne comme supprimée (surlignage rouge).

Pour plusieurs lignes consécutives, indiquez le nombre de lignes après un deux-points :

• // [!code ++:3] : Marquez la ligne actuelle plus les deux lignes suivantes comme ajoutées.
• // [!code --:5] : Marquez la ligne actuelle plus les quatre lignes suivantes comme supprimées.

La syntaxe de commentaire doit correspondre à votre langage de programmation (par exemple, // pour JavaScript ou # pour Python).

Diff example

const greeting = "Hello, World!"; 
function sayHello() {
  console.log("Hello, World!"); 
  console.log(greeting); 
}
sayHello();