Aller au contenu principal

Création de fichiers Markdown avec des blocs de code

astuce

Des blocs de code bien formatés en Markdown rendent votre documentation plus lisible et plus facile à maintenir.

Blocs de code de base​

Code en ligne​

Utilisez des backticks simples pour le code en ligne :

  • Mot unique : variable
  • Plusieurs mots : function parameter
  • Avec symboles : npm install package-name

Blocs de code délimités​

Utilisez des backticks triples pour le code multiligne :

Ceci est un bloc de code basique
Pas de coloration syntaxique

Coloration syntaxique spécifique au langage​

Ajoutez le nom du langage après les backticks d'ouverture :

const greeting = 'Hello, World!';
console.log(greeting);
def greet(name):
    print(f"Hello, {name}!")

Formatage avancé​

Numéros de ligne​

Certains processeurs Markdown prennent en charge les numéros de ligne :

// Cette ligne est surlignée
const x = 1;
// Ces lignes sont surlignées
// Ainsi que celle-ci
const y = 2;

Barres de titre​

Ajoutez des titres à vos blocs de code :

app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

Blocs de différences​

Montrez les changements de code avec la syntaxe diff :

- const oldCode = 'to be removed';
+ const newCode = 'to be added';
  const unchanged = 'stays the same';

Fonctionnalités MDX​

Blocs de code interactifs​

// Exemple JavaScript
function add(a, b) {
  return a + b;
}

Exemples de code en direct​

function Button() {
  return (
    <button onClick={() => alert('Cliqué !')}>
      Cliquez-moi
    </button>
  );
}

Langages courants​

Développement Web​

index.html
<!DOCTYPE html>
<html>
<head>
    <title>Exemple</title>
</head>
<body>
    <h1>Bonjour le monde</h1>
</body>
</html>
styles.css
body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 20px;
}
app.ts
interface User {
    name: string;
    age: number;
}

const user: User = {
    name: "John",
    age: 30
};

Développement Backend​

Main.java
public class Main {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
query.sql
SELECT users.name, orders.order_date
FROM users
JOIN orders ON users.id = orders.user_id
WHERE orders.status = 'completed';

Bonnes pratiques​

1. Formatage cohérent​

✅ À faire :

# Titre

## Section

\```javascript
// Code ici
\```

❌ À ne pas faire :

#Titre
##Section
\```javascript
//Code ici
\```

2. Spécification claire du langage​

✅ À faire :

\```python
def example():
    pass
\```

❌ À ne pas faire :

\```
def example():
    pass
\```

3. Indentation correcte​

✅ À faire :

- Élément de liste
  \```javascript
  const x = 1;
  \```

❌ À ne pas faire :

- Élément de liste
\```javascript
const x = 1;
\```

Cas spéciaux​

Commandes Shell​

Pour les instructions en ligne de commande :

# Commande avec sortie
$ npm install package
Installing package...
Done!

Variables d'environnement​

.env
API_KEY=your_api_key_here
DATABASE_URL=postgres://user:pass@localhost:5432/db

Fichiers de configuration​

package.json
{
  "name": "project",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js"
  }
}

Dépannage​

Problèmes courants​

  1. Backticks à l'intérieur des blocs de code

    \`\`\`
    Utilisez \` pour le code en ligne
    \`\`\`

  2. Sauts de ligne

    Ceci nécessite deux espaces  
    pour créer un saut de ligne

  3. Caractères d'échappement

    \* Pas un élément de liste
    \` Pas du code en ligne

Intégration avec l'éditeur​

Raccourcis Cursor​

ActionRaccourci
Bloc de codeCtrl + Maj + K
Code en ligneCtrl + `
AperçuCtrl + Maj + V

Extensions​

Extensions Markdown recommandées :

  • Markdown All in One
  • markdownlint
  • Markdown Preview Enhanced
astuce

Utilisez la fonction d'aperçu Markdown de Cursor pour vérifier votre formatage en temps réel !

Ressources connexes​