Simplonline Ressources - Thème Jekyll

⬅ English version

Un thème Jekyll pour créer des ressources pédagogiques (exercices, tutoriels, pages statiques) à destination des apprenants Simplonline. Marqué Wild Code School by Simplon.
Voir la version web

Installation

1. Préparer le projet

mkdir mon-site
cd mon-site
git init

Créez un .gitignore :

_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
Gemfile.lock

Ajoutez votre dépôt distant (remplacez l’URL par votre véritable dépôt) :

git remote add origin https://github.com/utilisateur/mon-site.git

2. Gemfile

Créez un Gemfile à la racine de votre projet :

source "https://rubygems.org"

gem "jekyll", "~> 4.3"
gem "webrick", "~> 1.8"
gem "jekyll-remote-theme"
gem "jekyll-readme-index"
gem "jekyll-stepper"

N’utilisez pas le gem github-pages. Il impose safe: true ce qui bloque les plugins non-autorisés comme jekyll-stepper.

⬇ Télécharger Gemfile

3. _config.yml

Créez un _config.yml avec la référence au thème et vos réglages :

remote_theme: simplonco/simplonline-ressources-jekyll-theme

title: "Titre de mon site"
description: "Description de mon site"
lang: fr

show_toc: true

readme_index:
  with_frontmatter: true

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge
  auto_ids: true

defaults:
  - scope:
      path: ""
    values:
      layout: default

plugins:
  - jekyll-readme-index
  - jekyll-remote-theme
  - jekyll-stepper

⬇ Télécharger _config.yml

Configuration options

4. Lancez le serveur

Pour tester localement vos contenus avant déploiement, il est nécessaire d’installer Jekyll sur votre machine.
Une fois cela fait, installez les dépendances du projet avec Bundler :

bundle install

Lancer le serveur Jekyll :

bundle exec jekyll serve --livereload

Votre site sera accessible à l’adresse http://localhost:4000.

Fonctionnement des pages

README.md est le point d’entrée de votre site. Il est automatiquement converti en index.html. Ajoutez d’autres pages en Markdown (ex : about.md, contact.md) à n’importe quel endroit du dépôt ; chacune devient une page de votre site.

Front Matter des pages

Chaque page peut définir ses métadonnées dans l’en-tête YAML :

---
title: Titre de la page
description: Description pour le SEO
show_toc: true
parent: Titre de la page parente
---

Fil d’Ariane

Le fil d’Ariane apparaît automatiquement quand la page a un parent dans son front matter et que cette page parente existe. La remontée traverse jusqu’à 4 niveaux.

Accueil > JavaScript > Variables

Si parent n’est pas défini, aucun fil d’Ariane n’est affiché.

Lien retour

Quand parent est défini, un lien “← Retour vers [titre parent]” apparaît en haut du contenu, juste sous le fil d’Ariane. Stylisé dans la couleur rouge du thème.

Table des matières

Activez avec show_toc: true dans le front matter de la page. La TOC est générée à partir des titres H2 à H6. Sur écran large (≥1200px), elle s’affiche en sidebar sticky ; sur les écrans plus petits, elle apparaît en haut du contenu.

La TOC est générée côté client par JavaScript. Tous les titres doivent avoir un attribut id (kramdown les génère automatiquement).

Colorisation syntaxique

Les blocs de code sont colorisés via Rouge (le surligneur par défaut de kramdown). Utilisez les blocs de code standards.

Langages supportés : tous les langages supportés par Rouge (JavaScript, CSS, HTML, Python, Ruby, Bash, YAML, etc.). Les blocs de code apparaissent avec un fond sombre et des couleurs syntaxiques qui s’adaptent automatiquement en mode sombre.

Exemple en JavaScript

```javascript
const name = "Alice";
let age = 25;
```

const name = "Alice";
let age = 25;

Exemple en CSS

```css
.card {
  background: #fff;
  border-radius: 8px;
}
```

.card {
  background: #fff;
  border-radius: 8px;
}

Blocs diff

Les blocs de code avec le language diff affichent des ajouts et suppressions en couleur :

​```diff
- const ancien = "supprimé";
+ const misAJour = "ajouté";
​```

- const ancien = "supprimé";
+ const misAJour = "ajouté";

Vidéos YouTube

Les liens YouTube sont automatiquement convertis en lecteur vidéo intégré sur GitHub Pages.

Syntaxe avec vignette (recommandée)

[![Titre vidéo](https://img.youtube.com/vi/ID_VIDEO/0.jpg)](https://youtu.be/ID_VIDEO)

Sur GitHub : affiche la vignette YouTube cliquable. Sur GitHub Pages : la vignette est remplacée par un lecteur iframe 16:9 avec YouTube en mode confidentialité renforcée (youtube-nocookie.com).

Syntaxe URL seule

https://youtu.be/ID_VIDEO

Auto-détectée et convertie de la même manière. Plein écran disponible.

Playground interactif

Intégrez un éditeur de code en direct avec aperçu grâce à l’inclusion playground.html.

{% capture mon_html %}
<h1>Bonjour le monde</h1>
{% endcapture %}

{% capture mon_css %}
h1 { color: red; }
{% endcapture %}

{% capture mon_js %}
console.log('Bonjour');
{% endcapture %}

{% include playground.html
  id="demo"
  initial_html=mon_html
  initial_css=mon_css
  initial_js=mon_js
%}

Les trois paramètres de code sont optionnels — passez seulement ce dont vous avez besoin.

Le playground affiche trois onglets (HTML, CSS, JS), un éditeur CodeMirror avec colorisation syntaxique, et un aperçu en direct. L’aperçu se met à jour automatiquement à chaque changement (délai de 300ms). Un bouton “Open in CodePen” exporte le code. Sur mobile, l’aperçu se replie sous l’éditeur avec un bouton “View result”.

Les sorties console.log, console.info, console.warn, console.error et console.debug du code exécuté s’affichent dans un tiroir « Console » sous l’aperçu — cliquez sur le bouton Console pour le déplier (un badge indique le nombre de messages). Les erreurs JavaScript non interceptées y sont également affichées en rouge ; inutile d’ouvrir la console du navigateur.

Pour démarrer sur un onglet autre que HTML :

{% include playground.html
  id="demo-js"
  initial_js=mon_js
  default_tab="js"
%}

For a minimal playground with small initial code, you can use inline code instead of {% capture %} blocks:

{% include playground.html
  id="mini"
  initial_html="<h1>Hello</h1>"
%}

Playground SQL

Intégrez un éditeur SQL dédié avec exécution grâce à l’inclusion sql-playground.html. Les requêtes s’exécutent entièrement dans le navigateur via sql.js (SQLite compilé en WebAssembly) — aucun serveur nécessaire.

{% capture db_schema %}
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  age INTEGER
);

INSERT INTO users VALUES
  (1, 'Alice', 30),
  (2, 'Bob', 22);
{% endcapture %}

{% capture requete_initiale %}
SELECT * FROM users;
{% endcapture %}

{% include sql-playground.html
  id="intro-sql"
  schema=db_schema
  query=requete_initiale
%}

Le playground SQL affiche un éditeur CodeMirror avec colorisation syntaxique SQL, un bouton « Exécuter », et un tableau de résultats. La base est recréée à chaque exécution (schema + query). Les messages d’erreur s’affichent dans un bloc rouge.

sql.js est chargé uniquement si un sql-playground est présent sur la page (~700 KB de WASM).

Pour un exemple en direct, voir la démo SQL.

Solution intégrée au contenu

Si vous souhaitez inclure une solution dans votre contenu (par exemple pour des exercices, des solutions de playground, etc.), vous pouvez utiliser l’élément HTML <details markdown="1"> pour créer une section rétractable. Cela permet à l’apprenant de révéler la solution uniquement quand il le souhaite. L’attribut markdown="1" active le rendu Markdown à l’intérieur des balises <details> et <summary>.

Exemple

<details markdown="1">
<summary>Voir la solution</summary>
```html
<h1>Bonjour le monde</h1>
```
```css
h1 { color: red; }
```
```javascript
console.log('Bonjour');
```
</details>

Donne :

<h1>Bonjour le monde</h1>

h1 { color: red; }

console.log('Bonjour');

Quiz interactif

Intégrez un QCM interactif dans vos pages avec l’inclusion quiz.html.

{% capture quiz_data %}
[{"question":"Que signifie HTML ?","options":["Hyper Text Markup Language","High Tech Modern Language","Home Tool Markup Language","Hyper Transfer Markup Language"],"correct":0}]
{% endcapture %}
{% include quiz.html data=quiz_data %}

Format d’une question :

{
  "question": "L'intitulé",
  "options": ["Option A", "Option B", "Option C", "Option D"],
  "correct": 0
}

• question (string) — l’intitulé de la question
• options (array) — les choix proposés
• correct (number ou array) — index de la réponse unique, ou tableau d’indices pour les réponses multiples

Exemple à réponse unique :

{"question":"Que signifie HTML ?","options":["Hyper Text Markup Language","High Tech Modern Language","Home Tool Markup Language","Hyper Transfer Markup Language"],"correct":0}

Exemple à réponses multiples :

{"question":"Langages de programmation ?","options":["HTML","Python","CSS","JavaScript"],"correct":[1,3]}

Le quiz rend chaque question dans un <fieldset> avec legend. Le type d’input (radio ou checkbox) est automatiquement choisi selon que correct soit un nombre ou un tableau. Un bouton “Valider” déclenche le feedback visuel : vert pour les bonnes réponses, rouge pour les mauvaises. La navigation clavier est supportée (Tab, flèches, Enter).

Exemple en direct :

Stepper

Le composant stepper crée un accordéon avec navigation pour les tutoriels pas à pas. Utilisez un bloc de code avec l’identifiant de langage stepper.

Syntaxe

Utilisez 4 backticks pour le bloc extérieur (pour autoriser les blocs de code imbriqués) :

````stepper
# Titre de l'étape

Contenu en markdown...

# Autre étape

```html
<h1>Bonjour le monde</h1>
```
````

Fonctionnement

• Chaque # Titre devient un en-tête d’accordéon (<summary>)
• Le contenu entre les titres est rendu en markdown
• Une barre de navigation avec les boutons Précédent/Suivant est ajoutée automatiquement
• La première étape est ouverte par défaut
• Une seule étape peut être ouverte à la fois

Exemple

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Mon site</title>
</head>
<body>
    <p>Hello World</p>
</body>
</html>

Classes utilitaires

Grâce au parser Markdown de kramdown, vous pouvez ajouter des classes à n’importe quel élément bloc en ajoutant {:.nomdeclasse} après le bloc. Par exemple :

Classes utilitaires disponibles :

• alert-info — bordure bleue à gauche, pour les messages informatifs
• alert-warning — bordure orange à gauche, pour les avertissements
• text-center — centre le texte
• text-end — aligne le texte à droite

**Info** : Pensez à vérifier votre syntaxe.
{: .alert-info}

**Attention** : Cette fonctionnalité est dépréciée.
{: .alert-warning}

**Texte centré**
{: .text-center}

**Texte aligné à droite**
{: .text-end}

**Exemple combiné** :
Encadré d'alerte avec style warning et texte centré.
{: .alert-warning .text-center}

Info : Pensez à vérifier votre syntaxe.

Attention : Cette fonctionnalité est dépréciée.

Texte centré

Texte aligné à droite

Exemple combiné :
Encadré d’alerte avec style warning et texte centré.

Citations

Utilisez les blocs de citation :

> Ceci est une citation.  
> Elle peut s'étendre sur plusieurs lignes.

Ceci est une citation.
Elle peut s’étendre sur plusieurs lignes.

Conseils

Saut de ligne avec deux espaces en fin de ligne, ou utilisez <br> pour un saut forcé :

Ceci est une ligne avec un saut après celle-ci.  
Voici la ligne suivante.

Ceci est une ligne avec un saut forcé.<br>
Voici la ligne suivante.

Ceci est une ligne avec un saut après celle-ci.
Voici la ligne suivante.

Ceci est une ligne avec un saut forcé.
Voici la ligne suivante.

Démo

• Démo playground interactif
• Démo playground SQL