Skip to content

maitreverge/github_readme

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
assets
assets
 
 
img
img
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 

Repository files navigation

🚀 SYNOPSIS

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.

⚙️ USAGE

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.

Sommaire

-----------------------------------------------------

BASICS

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é~~ 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

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 :

  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

-----------------------------------------------------

HEADINGS

Pour le heading, nous utiliserons le symbole #

Markdown :

# HEADING 1

Preview :

HEADING 1

Markdown :

## HEADING 2

Preview :

HEADING 2

Markdown :

### HEADING 3

Preview :

HEADING 3

Markdown :

#### HEADING 4

Preview :

HEADING 4

Markdown :

##### HEADING 5

Preview :

HEADING 5

Markdown :

###### HEADING 6

Preview :

HEADING 6

-----------------------------------------------------

IMAGES

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

![Hold The Pain Harold](assets/pain.png)

Preview :

Hold The Pain Harold

CENTRER LES IMAGES :

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 :

center_cockie_monster

Aligner a gauche :

<p align="left">
  <img src="assets/left.gif" alt="left_cockie_monster">
</p>

Preview :

left_cockie_monster

Aligner a droite :

<p align="right">
  <img src="assets/right.gif" alt="right_cockie_monster">
</p>

Preview :

right_cockie_monster

-----------------------------------------------------

LINKS

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

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).

-----------------------------------------------------

TABLEAUX

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

-----------------------------------------------------

ADVANCED_SYNTAX

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 :

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

EXTRAS

Ressources on Markdown

Cool profiles

About

Essentials Markdown syntax for GitHub ✍️

Resources

Readme
Activity

Stars

5 stars

Watchers

1 watching

Forks

0 forks
Report repository