Contribuer au site

Le site Do_It est un site constitué de fichiers écrit au format Markdown. Y contribuer est très simple, il suffit de suivre ce document.

Architecture d'un post

Un post Do_It est un dossier à mettre dans le code source du site. Par exemple, cette page est le dossier https://github.com/FrancoisBrucker/do-it/tree/main/src/cs/contribuer-au-site

Ce dossier contient :

• un fichier index.md qui est le texte de votre post
• les images ou autres fichier de ressources (code source, données, etc) que vous voulez montrer.

Il y a 3 endroits où placer ses contributions :

• dans le dossier cs
• dans le dossier pok
• dans le dossier mon

Post cs

Votre dossier de post doit s'appeler comme l'intitulé du cours, en remplaçant les espace par des -.

Par exemple ce post s'appelle contribuer-au-site et est rangé dans le dossier cs :

src
└── cs
    ├── contribuer-au-site
    │   └── index.md
    └── index.njk

Post pok

Comme plusieurs groupes de personnes peuvent faire le même pok, on ajoute une indirection. Votre dossier de post doit s'appeler des initiales des personnes constituant le groupe (séparés par des -) et être placé dans le dossier du pok correspondant. Par exemple si j'avais avec Geo fait le pok "un site chez moi", le post aurait été nommé FB-GD, et aurait été de cette forme :

src
└── pok
    ├── un-site-chez-moi
    │   ├── FB-GD
    │   │   ├── index.njk
    │   │   └── sources.zip
    │   ├── RS
    │   └── index.njk
    └── index.njk

Il aurait en effet contenu, en plus du fichier index.md les sources du site compressées au format zip.

Post mon

De la même manière que le poste pok.

Le fichier index.md

Il est constitué de trois parties :

• l'entête
• son résumé
• le corps du texte en markdown

Exemple

Ce fichier est visible à cette adresse.

Entête

Ce sont les premières lignes du site. Elles contiennent les méta-données du post :

• le layout html à utiliser
• le titre du post
• le ou les auteurs (il suffit d'ajouter une ligne)
• les tags du site. Doit au minimum contenir cs si vous faite un cs, pok si vous faites un pok et mon si vous faites un mon.

---
layout: layout/post.njk

title: "Contribuer au site"
authors:
  - François Brucker
résumé: "Comment contribuer au site Do_It."

tags:
  - 'cs'
---

Résumé

Dans l'entête.

corps du texte

Le reste du post, écrit en markdown. Le titre est déjà mis, vos différentes parties sont donc de niveau ##

les ressources

Placez les ressources dans le même dossier que votre post. Vos liens auront alors l'une des deux formes suivantes

Ressources à télécharger

[ressource à télécharger](./sources.zip)`{.fichier}

Images

![image à voir](./mon-image.png)`{.fichier}

Possibilités étendues en markdown

Plusieurs balises spéciales ont été ajoutées pour vous aider à écrire des parties spécifiques de votre post.

liens

Il existe plusieurs façons d'écrire les liens. On suppose que l'on a l'architecture suivante :

src
└── pok
    ├── un-site-chez-moi
    │   ├── FB-GD
    │   │   ├── index.njk
    │   │   └── sources.zip
    │   ├── RS
    │   └── index.njk
    ├── index.njk
    └── cs
       ├── contribuer-au-site
       │   └── index.md
       └── index.njk

Et que l'on veuille, depuis le post FB-GD, aller vers le post contribuer-au-site.

Il y a deux façons de faire :

• lien absolu. Depuis la racine du site (qui est src) [lien](/do-it/cs/contribuer-au-site)
• lien relatif. Depuis là on je suis : [lien](../../../cs/contribuer-au-site) (je remonte 3 dossier avant de redescendre dans l'arborescence)

Texte spécial

En plus des possibilités markdown, on ajoute deux distinctions de texte :

• fichier : nom-fichier que l'on écrit : `nom-fichier`{.fichier}
• code : print("coucou !") que l'on écrit : `print("coucou !")`{.language-}

Shortcodes

Les shortcodes sont des aides markdown. Elles permettent de mettre en valeur un paragraphe. elles sont toutes de la même forme :

{% nom_shortcode "titre de la shortcode" %}

le contenu de la shortcode.

{% endnom_shortcode %}

Shortcode attention

Code :

{% attention "**faisez** attention" %}
Une *grosse* mise en garde.
{% endattention %}

Shortcode note

Nom de la shortcode : note

Code :

{% note %}
Une note à retenir.
{% endnote %}

Shortcode info

Code :

{% info %}
Un truc marrant ou une information utile, mais pas indispensable.
{% endinfo %}

Shortcode faire

Code :

{% faire %}
Quelque-chose à faire.
{% endfaire %}

Shortcode details

Le titre de la shortcode est automatiquement mis en gras.

Code :

{% details "titre de la shortcode" %}
Quelque chose de caché. Que l'on peut *écrire* en `Markdown`
{% enddetails %}

Shortcode exercice

On peut le combiner avec la shortcode details pour créer un exercice et son corrigé :

Code :

{% exercice %}
Sujet de l'exercice
{% endexercice %}
{% details "corrigé" %}
Le corrigé de l'exercice.
{% enddetails %}

Shortcode chemin

Pour emmener vers un autre cours par exemple :

Code :

{% chemin %}
[Cours do-it de FB](https://francoisbrucker.github.io/cours_informatique/enseignements/ecm/3A/do-it/)
{% endchemin %}

Shortcode prerequis

Code :

{% prerequis %}

- un pré-requis à lire
- un autre pré-requis à lire

{% endprerequis %}

Shortcode lien

Code :

{% lien %}

- [un MON utile](/promos/2023-2024/Lucie-Le-Boursicaud/mon/temps-2.2/)
- [un cours qui sert](https://francoisbrucker.github.io/cours_informatique/cours/web/)

{% endlien %}

Écrire du code

Pour écrire du code, le thème prismjs se chargera de la coloration syntaxique.

Par exemple :

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <link rel="icon" href="assets/favicon.png" />
        ...
    </head>
    <body class="language-none">
    <header data-plugin-header="line-numbers"></header>
    <section class="language-markup">
      <h1>How to use</h1>
      ...
    </body>
</html>

Peut s'écrire avec le markdown suivant :

    
```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <link rel="icon" href="assets/favicon.png" />
        ...
    </head>
    <body class="language-none">
    <header data-plugin-header="line-numbers">
    <section class="language-markup">
      <h1>How to use
      ...
    </body>
</html>
```
    

Également, il est possible d'ajouter les numéros de ligne comme ceci :

print(42)
print(43)

Avec le code :

    
```python/
print(42)
print(43)
```
    

Tables

On utilise les possibilités de multimarkdown

Table avec titre

Code :

| titre colonne 1  | titre colonne 2 |
| ---------------- | --------------- |
| Content Cell     | Content Cell    |
| Content Cell     | Content Cell    |

Tables sans titre

Code :

| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

Tables multi-colonnes

Code :

| ------------- | ------------- |
| Je prends 2 colonnes ||
| Content Cell | Content Cell |

Tables multi-lignes

Code :

| ------------- | ------------- |
| Je prends 2 lignes |Content Cell |
| ^^ |Content Cell |
| Content Cell | Content Cell |

plusieurs ligne dans une cellule

Code :

| ------------- | ------------- |
| 1. ligne colonne 1 | 1. ligne colonne 2 | \
| 1. ligne colonne 1 | 2. ligne colonne 2 |
| Content Cell | Content Cell |

Alignement horizontal

Code :

| :- | :-: | -: |
| Content Cell | Content Cell | Content Cell |
| Content Cell | Content Cell |Content Cell |
| Content Cell | Content Cell |Content Cell |

Alignement vertical

On ajoute un style, mais il ne faut pas que ce soit la dernière colonne. Exemple sur une colonne multi-ligne :

Code :

| ------------- | ------------- |
| Content Cell {style="vertical-align:middle"}| Content Cell |
| ^^| Content Cell |
| Content Cell | Content Cell |

Si l'on veut avoir un alignement vertical de la dernière colonne, il faut ajouter une colonne vide (je ne sais pas trop pourquoi) :

Code :

| ------------- | ------------- | - |
| Content Cell | Content Cell {style="vertical-align:middle"}| |
| Content Cell | ^^ | |
| Content Cell | Content Cell | |

tbd

TBD

• résumé :

  1. toujours pris en compte : dans l'entête
  2. dans les résumés si pas 1
     1. premier paragraphe
     2. entre balise

• pok, mon, mon-index, pok-index, projet

• entête, pas de [] que des listes