Ceci est un guide non exhaustif des possibilités de mise en page sur un README.md sur GitHub.
Note
Ce guide a été écrit dans un premier temps pour servir de support pédagogique lors d'un atelier à 42.
J'ai ensuite fait les modifications nécessaires pour que ce guide serve à tous.
La syntaxe utilisee est du Markdown :
Le Markdown est un langage de balisage léger utilisé pour formater du texte de manière simple et intuitive.
Il permet de créer des documents avec une mise en forme basique, comme des titres, des listes, des liens hypertexte, des images, etc., en utilisant des symboles facilement reconnaissables.
Markdown :
Ceci est un exemple basique.
Notez la difference entre un seul saut de ligne
et deux sauts de ligne
Preview :
Ceci est un exemple basique. Notez la difference entre un seul saut de ligne
et deux sauts de ligne
On peut egalement mettre du texte en gras, italique, gras plus italique, gras et italique barré...
Style | Syntax | Raccourci clavier | Example | Output |
---|---|---|---|---|
Texte en gras | ** ** ou __ __ (double underscore) |
Command +B (Mac) or Ctrl +B (Windows/Linux) |
**Texte en gras** ou __Texte En gras__ |
Texte en gras |
Texte en italique | * * ou _ _ (single underscore) |
Command +I (Mac) or Ctrl +I (Windows/Linux) |
*Texte en italique* ou _Texte en italique_ |
Texte en italique |
Texte barré | ~~ ~~ |
/ | ~~Texte barré~~ |
|
Gras et italique imbriqués | ** ** et _ _ |
/ | **Texte _urgent_ et important** |
Texte urgent et important |
Tout en gras et en italique | *** *** |
/ | ***Tout en gras et en italique*** |
Tout en gras et en italique |
Code | ` ` | / | `Ceci est un bout de code` |
Ceci est un bout de code |
Subscript | <sub> </sub> |
/ | Ceci est un <sub> subscript </sub> texte |
Ceci est un subscript texte |
Superscript | <sup> </sup> |
/ | Ceci est un <sup> superscript </sup> texte |
Ceci est un superscript texte |
Code couleurs :
Couleur | Syntax | Example | Output |
---|---|---|---|
HEX | #RRGGBB |
#0969DA |
#0969DA |
RGB | rgb(R,G,B) |
rgb(9, 105, 218) |
rgb(9, 105, 218) |
HSL | hsl(H, S, L) |
hsl(212, 92%, 45%) |
hsl(212, 92%, 45%) |
Note
Les codes couleurs fonctionnent uniquement dans les sections Issues
, Pull requests
et Discussions
.
Des syntaxes plus poussees sont egalement possibles :
Markdown :
Ceci n'est pas une citation
> Ceci est une deuxieme citation
Preview :
Ceci n'est pas une citation
Ceci est une deuxieme citation
Bullet points (liste non ordonee)
Markdown :
* Un premier point en utilisant * avec un espace
+ Un deuxieme point en utilisant + avec un espace
- Un troisieme point en utilisant - avec un espace
[Tabulation] - Sous-Point
[Tabulation] [Tabulation] - Sous-sous-Point
Preview :
- Un premier point en utilisant * avec un espace
- Un deuxieme point en utilisant + avec un espace
- Un troisieme point en utilisant - avec un espace
- Sous-Point
- Sous-sous-Point
- Sous-Point
Liste ordonees :
Markdown :
1. Un premier point en utilisant 1. avec un espace
2. Un deuxieme point en utilisant 2. avec un espace
3. Un troisieme point en utilisant 3. avec un espace
- Sous point
- Encore un sous-point
Preview :
- Un premier point en utilisant 1. avec un espace
- Un deuxieme point en utilisant 2. avec un espace
- Un troisieme point en utilisant 3. avec un espace
- Sous point
- Encore un sous-point
Pour le heading, nous utiliserons le symbole #
Markdown :
# HEADING 1
Preview :
Markdown :
## HEADING 2
Preview :
Markdown :
### HEADING 3
Preview :
Markdown :
#### HEADING 4
Preview :
Markdown :
##### HEADING 5
Preview :
Markdown :
###### HEADING 6
Preview :
Pour inserer des images, nous pouvons utiliser deux methodes : une balise HTML
, ou une balise Markdown
:
Balise HTML :
<img src="chemin_vers_votre_image.jpg" alt="Description de l'image">
Balise Markdown :
![Description de l'image](chemin_vers_votre_image.jpg)
Exemples :
<img src="assets/pain.png" alt="Hold the Pain Harold">
Preview :
![Hold The Pain Harold](assets/pain.png)
Preview :
Important
Bien que le Markdown
supporte l'insertion d'image, ce dernier ne permet pas d'alligner les images. Pour remerdier a cela, nous utiliseront les balises HTML
.
Center une image :
<p align="center">
<img src="assets/middle.gif" alt="center_cockie_monster">
</p>
Preview :
Aligner a gauche :
<p align="left">
<img src="assets/left.gif" alt="left_cockie_monster">
</p>
Preview :
Aligner a droite :
<p align="right">
<img src="assets/right.gif" alt="right_cockie_monster">
</p>
Preview :
Markdown :
[Lien classique](https://www.google.com)
[Lien classique avec description](https://www.google.com "Ceci est la description du lien : Page d'accueil de Google")
[Je suis une référence relative à un fichier de dépôt](assets/pain.png)
Les URL et les URL entre crochets seront automatiquement transformés en liens.
http://www.example.com ou <http://www.example.com> et parfois
exemple.com (mais pas sur Github, par exemple).
Preview :
Lien classique avec description
Je suis une référence relative à un fichier de dépôt
Les URL et les URL entre crochets seront automatiquement transformés en liens. http://www.example.com ou http://www.example.com et parfois exemple.com (mais pas sur Github, par exemple).
Pour creer des tableaux simples, nous allons utiliser deux caracteres principaux : le pipe |
et le tiret -
Markdown :
| Colonne 1 | Colonne 2 |
| ------------- | ------------- |
| Hello World | Elon Musk is my Daddy |
| Epitech is over-rated | Jennifer Lopez is my Mommy |
Preview :
Colonne 1 | Colonne 2 |
---|---|
Hello World | Elon Musk is my Daddy |
Epitech is over-rated | Jennifer Lopez is my Mommy |
Tip
Le formatage est egalement possible dans les cellules d'un tableau :
Markdown :
| Command | Description |
| --- | --- |
| `git push --force` | Commande a tester *SEULEMENT* en production. |
| `git reset --hard HEAD && git push --force` | L'architecture **chaos** |
Preview :
Command | Description |
---|---|
git push --force |
Commande a tester SEULEMENT en production. |
git reset --hard HEAD && git push --force |
L'architecture du chaos |
Tip
Une syntaxe speciale est utilisee pour aligner les cellules d'une meme colonne :
Markdown :
| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| git status | git status | git status |
| git diff | git diff | git diff |
Preview :
Left-aligned | Center-aligned | Right-aligned |
---|---|---|
git status | git status | git status |
git diff | git diff | git diff |
GitHub supporte egalement la syntaxe les cases cochees :
Markdown :
- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:
Preview :
- #739
- https://github.com/octo-org/octo-repo/issues/740
- Add delight to the experience when all tasks are complete 🎉
Github permet egalement d'annoter ses README.md avec 5 balises de couleurs :
Markdown :
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
Preview :
Note
Useful information that users should know, even when skimming content.
Tip
Helpful advice for doing things better or more easily.
Important
Key information users need to know to achieve their goal.
Warning
Urgent info that needs immediate user attention to avoid problems.
Caution
Advises about risks or negative outcomes of certain actions.
Pour la mise en page de blocs de code, nous utiliseront les triples ```language ```
afin que GitHub puisse appliquer des couleurs de syntaxes propres a chaque language.
Markdown :
```python
s = "Hello, World ! This is Python."
print s
```
```javascript
var message = "Hello, World ! This is JavaScript.";
console.log(message);
```
```c
#include <stdio.h>
int main() {
char message[] = "Hello, World! This is C language.";
printf("%s\n", message);
return 0;
}
```
```bash
gcc -Wall -Wextra -Werror && rm -rf */*
```
```
Lorsque non precise, le bloc de code sera affiche sans syntax highlighting
```
Preview :
s = "Hello, World ! This is Python."
print s
var message = "Hello, World ! This is JavaScript.";
console.log(message);
#include <stdio.h>
int main() {
char message[] = "Hello, World! This is C language.";
printf("%s\n", message);
return 0;
}
gcc -Wall -Wextra -Werror && rm -rf */*
Lorsque non precise, le bloc de code sera affiche sans syntax highlighting
Ressources on Markdown
Cool profiles
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- student_1
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- cool_profile
- A precious Ressource