Avant de démarrer
Pour utiliser ces tutos
- Le langage utilisé est le Markdown (saveur mkdocs)
- Nous utiliserons un vocabulaire spécifique présenté ici.
- Le code peut être copié/collé facilement
I. Pour démarrer⚓︎
Le langage Markdown⚓︎
Le langage utilisé pour écrire le site est le Markdown.
La syntaxe est très simple. Vous en verrez une présentation ici :
Pour composer vos documents, on peut écrire directement dans l'éditeur WEB IDE de la forge et utiliser le bouton «Créer un commit» comme un bouton sauvegarder. La différence par rapport à une sauvegarde «classique» est que vous êtes invités à commenter la ou les modifications apportées afin de créer un historique des modifications successives. Pour les utilisateurs avancés, on peut travailler localement, mais cela sera précisé dans un autre tutoriel.
La structure du site⚓︎
Le choix retenu pour ces modèles est de construire un site dont la page d'accueil est le contenu généré depuis le fichier index.md
et les pages suivantes sont prises par ordre alphabétique de nom de dossier/fichier.
Ainsi, si la structure du répertoire docs
est la suivante (comme dans le site modèle) :
docs/
├── 01_chapitre_1
│ └── chapitre_1.md
├── 02_chapitre_2
│ ├── scripts
│ ├── 1_intro_python.md
│ ├── 2_fonction.md
│ ├── 3_liste.md
│ └── .pages
├── index.md
└── tags.md
index.md
, et en menu les titres spécifiés au début des fichiers avec pour extension .md
comme expliqué ci-dessous.
---
author: compléter avec les noms d'auteurs
title: Compléter le titre qui sera affiché dans le menu
---
Si vous êtes amenés à séparer le contenu de votre chapitre en plusieurs pages, vous pouvez rajouter un fichier .pages
qui contiendra le titre affiché au menu du site pour l'ensemble de ces pages.
Ici par exemple :
En l'absence de ce fichier.pages
le menu du site affichera le nom du dossier, c'est à dire ici chapitre 2 (et non Chapitre 2 - Python).
Le rendu du site modèle correspondant à cette structure est le suivant :
II. Le vocabulaire⚓︎
Indentation⚓︎
-
Une indentation est un décalage vers la droite de 4 espaces (souvent réalisé automatiquement avec la touche tabulation du clavier)
-
Un texte indenté est un texte pour lequel toutes les lignes sont indentées :
Ceci est un texte indenté.
Toutes les lignes sont décalées de 4 espaces vers la droite.
Il ne faut pas oublier les indentations lorsqu'elles sont nécessaires.
C'est souvent la cause de problèmes de rendu.
Ceci est un texte non indenté.
Toutes les lignes commencent au début de la ligne.
Il ne faut pas oublier les indentations lorsqu'elles sont nécessaires.
C'est souvent la cause de problèmes de rendu.
Backtick ou apostrophe inversée⚓︎
Pour écrire un morceau de code dans un texte, Markdown l’identifie au moyen du caractère appelé le Backtick ou apostrophe inversée (`
). Attention, à ne pas le confondre avec les guillemets. On le trouve généralement avec la touche ALT GR + è du clavier.
Les "admonitions"⚓︎
Les « admonitions » sont les « boîtes » comme celles-ci. Elles peuvent s'imbriquer les unes dans les autres.
Question
Résoudre cet exercice. Mon énoncé
Astuce 1
Ma belle astuce 1
Astuce 2
Ma belle astuce 2
Astuce 3
Ma belle astuce 3
Solution
La solution
Remarque
texte de la remarque indenté
Les "IDE"⚓︎
Nous appelons IDE une fenêtre dans laquelle nous pouvons écrire du code.
III. Récupérer la syntaxe pour réaliser votre site⚓︎
Copier les syntaxes
Il suffit de cliquer en haut à droite de la syntaxe à recopier sur l'icône suivante
Vous n'aurez plus qu'à effectuer un "coller" dans le document de votre site.
IV. Personnaliser la page d'accueil du site que vous avez cloné⚓︎
La page d'accueil se trouve dans le fichier index.md
du dossier docs
.
😀 Il suffit de la personnaliser.