HTML, CSS & templating

zvqt3Z-fSBuFPO6MCmcGdw (edit on libreon)

created: 2024-10-03

updated: 00:20:34 - October 9, 2024

tags: #extensions #job12 #Anatomie_d #lastone #ajouter #Baliser_le_texte #layout #cssyaml #romeo

HTML, CSS & templating

2024

Accueil

Cette page vous donne quelques éléments théoriques et pratiques sur les langages HTML et CSS en vue de personnaliser vos pages Pink My Pad sur la base des layouts existants, et/ou de concevoir votre propre layout.

Comme d’habitude, les différents encarts sont codifiés:

Encart Info : vous donne des informations sur le sujet

Encart Activité : vous donne des consignes à appliquer.

Encart Ressource : vous donne des ressources sur le sujet

Encart Attention : attire votre attention sur un point particulier, un risque ou une erreur à éviter.

Dans le cadre des principes HTML et CSS, cet encart indiquera des aspects propres à Pink My Pad.

### Encart de code

présente du code dans les différents langages
que l'on utilisera : `HTML`, `CSS`, `Markdown`.

Principes du HTML

Notions : document, balise, élément, identifiant, classe, contenu.

HTML est un langage de balisage utilisé pour éditer et mettre en forme des contenus sur le Web.

Une “page web” est donc le résultat d’un document édité au format HTML.

Les navigateurs (Firefox, Chrome, Edge, etc.) nous permettent de visualiser une version “interprétée” des documents HTML, c’est-à-dire mise en forme. Depuis le navigateur, il est possible de consulter la source (document HTML) d’une page web.

Ressource: Les bases HTML (developer mozilla)

Anatomie d’un élément HTML:

Un élément est constitué d’une balise ouvrante, d’un contenu et d’une balise fermante

Attributs:

Les éléments peuvent aussi avoir des “attributs” qui permettront d’identifier l’élément ou de le rendre opérationnel. Ils sont déclarés dans la balise ouvrante :

Classe:

Une classe est un attribut particulier d’un élément. Elle est notamment utile pour mettre en forme le document. Le langage CSS associe une série de règles de mise en forme (“styles”) aux classes définies dans le document.

Un élément peut appartenir à plusieurs classes. Il suffit alors de les déclarer à suite dans l’attribut class. Par exemple :

<p class="commentaire primary">Mon paragraphe</p>

Identifiant:

Un identifiant est un attribut particulier d’un élément. Il permet d’identifier l’élément de manière unique. C’est utile pour appliquer un style CSS particulier, ou pour “se déplacer” dans le document.

<h2 id="romeo">La vie de Roméo</h2>

On peut utiliser cet identifiant comme cible d’un hyperlien en ajoutant un # devant l’identifiant :

Voici <a href="#romeo">un hyperlien</a> pointant
vers le titre précédent.

Document HTML

Un document HTML est un contenu encodé ou balisé dans le langage HTML. Toutes les pages affichées par votre navigateur sont issues d’un document “source” HTML.

Consulter la source HTML d’une page web

Dans votre navigateur, ouvrez la page votre page de veille thématique
Consultez la source HTML de la page : pressez CTRL+U ou trouvez dans le menu Code source de la page

→ Qu’est ce qui s’affiche ? Comment comprenez-vous les éléments de cette page ?

Structure minimale d’un document HTML

Voici la structure minimale d’un document HTML. On remarque différents éléments html, head, body, …

<!DOCTYPE html> 
<html>          
    <head>      
    <meta charset="utf-8"> 
    <title>page01 - Ma page de test</title> 
    </head>     
    <body>      
    <h1>Ma page de test</h1> 
    <p>Bienvenu sur ma page de test.</p> 
    </body>     
</html>

Élément	Description
`<!DOCTYPE html>`	déclare le type de document
`<html>`	la balise html contient toutes les autres
`<head>`	la balise head contient les métadonnées et des éléments associés à la page (styles, scripts)
`<meta charset="utf-8">`	voici une balise de metadonnées → ici le type de caractères
`<title>page01 - Ma page de test</title>`	voici une donnée “title”
`</head>`	fin de la balise head
`<body>`	la balise body contient tout le contenu qui sera affiché par le navigateur
`<h1>Ma page de test</h1>`	Voici un élément ‘titre de niveau 1’. Il n’est pas corrélé à la balise title
`<p>Bienvenu sur ma page de test.</p>`	Voici un élément ‘paragraphe’
`</body>`	fin de la balise body
`</html>`	fin de la balise html

Le langage HTML intègre des dizaines d’éléments différents. Nous en verrons quelques uns à la section suivante.

Imbrication des éléments:

Les éléments peuvent s’imbriquer les uns dans les autres, mais ne peuvent pas se chevaucher.

incorrect <p>Bonjour <strong>Monsieur.</p></strong>
correct: <p>Bonjour <strong>Monsieur</strong>.</p>

Lors de l’édition, on matérialise l’imbrication avec une indentation:

<html>
    <head>
        <title>Hello World</title>
    </head>
    <body>
        <p>
            Hello World!
        </p>
    </body>
</html>

Cette règle d’imbrication impose au document HTML une structure arborescente, c’est-à-dire constituée d’un tronc (<html>), puis de deux branches principales (<head>, <body>), puis pour chacune des branches, des sous-branches, chacune pouvant contenir d’autres sous-branches, etc. On peut représenter cette arborescence en listes imbriquées :

html
- head
  - meta
  - title
- body
  - h2
  - p

Reconstituez l’arborescence de votre page

Retournez à la source HTML de votre page de veille thématique et retracez la structure arborescente de votre page en identifiant ses principales branches.

Représentez cette arborescence en listes imbriquées.

Éléments HTML pour baliser le texte.

Rappel: Les documents HTML des pages Pinkmypad sont générées automatiquement à partir des pads Hedgedoc.

Nous éditons ces pads au format Markdown. Les éléments Markdown sont automatiquement transformés en HTML.

Nous n’aurons donc pas à écrire et éditer du HTML.

Ressource : voir Baliser le texte (Mozilla)

Titres

éléments <h1>, <h2>, <h3>, etc. : pour heading

Rappel: En markdown, les headings sont identifiés par la syntaxe suivante en début de ligne : #, ##, ###, etc. qui génére les éléments HTML <h1>, <h2>, <h3>, etc.

Paragraphe

élément <p> : pour paragraph

Rappel: En markdown, un paragraphe est identifié par un saut de ligne avant et après un texte. Par exemple:


Un paragraphe pour ne rien dire.

Un autre paragraphe
qui ne veut rien dire non plus.

donnera en HTML

<p>Un paragraphe pour ne rien dire.</p>
<p>Un autre paragraphe qui ne veut rien dire non plus.</p>

Listes

éléments <ul> pour un-ordered list, <ol> pour ordered list.

Chaque item de la liste est un élément <li> pour list item.

Soit :

<ul>
    <li>un item</li>
    <li>un autre item</li>
    <li>encore un</li>
</ul>

Rappel: En markdown, une liste est créée en démarrant la ligne par un signe - ou + ou encore *. Pour une liste ordonnée, on démarre la ligne avec 1., 2., etc.

Liens

élément <a>: pour anchor ou ancre. Exemple: Allez voir <a href="https://page.com/que-vous-pointez/">cette page</a>

Il existe différents types de lien:

lien externe → pointe hors du site en cours :
<a href="https://wikipedia.org/">Wikipédia</a>
lien interne → pointe vers le site en cours :
<a href="./page02.html">Page 02</a>
ancre → pointe vers une ancre (identifiant) dans la page en cours :
<a href="#romeo">remonter à la section précédente "La vie de Roméo"</a>

Rappel: la syntaxe Mardown de ces hyperliens sera respectivement :

[Wikipédia](https://wikipedia.org)
[Page 02](./page02.html)
[remonter à la section précédente "La vie de Roméo"](#romeo)

Images

élément <img/>

C’est un “élément vide” (voir ci-dessous), les données sont donc introduites en attributs:

<img src="https://upload.wikimedia.org/wikipedia/commons/Alice_par_John_Tenniel_02.png" alt="Alice">

src (source): indique l’URL de l’image
alt (alternatif): indique un message qui peut servir d’alternatif si l’image n’est pas chargée par le navigateur.

Rappel: la syntaxe d’une image en Markdown sera :

![Légende de l'image](https://url.de/la-source-de-limage.jpg)

Remarquez aussi que le convertisseur de Pinkmypad produit un élément HTML <figure> plus complexe qu’un simple élément <img>:

<figure>
  <img src="https://url.de/la-source-de-limage.jpg" alt="Légende de l'image">
  <figcaption aria-hidden="true">Légende de l'image</figcaption>
</figure>

Éléments vides:

Il existe des éléments vides, c’est-à-dire sans contenu. L’élément intègre alors sa fermeture dans une balise dite “auto-fermante” : <img/>, <br/>

Image: le contenu de l’image est intégré dans un attribut src (source): <img src="chaton.jpg"/>
Saut de ligne: <br/>

Commentaires

Il est possible d’ajouter des commentaires dans les documents HTML. Ces commentaires ne seront pas affichés par le navigateur. Ils sont utiles pour documenter le code HTML de la page par exemple.

Pour aller plus loin sur les éléments HTML:

les ressources de W3Schools

Principes du CSS

CSS est l’acronyme de Cascading Style Sheets ou « feuilles de style en cascade ».

Feuilles de style : les règles de mise en forme d’un contenu HTML (une page ou un site web par exemple)

Cascade : la manière dont les règles sont prises en compte, notamment le principe selon lequel la dernière instruction prévaut.

Ressource : sur cette notion de cascade, voir la ressource MDN/cascade et héritage

Syntaxe des règles CSS

Une règle CSS définit comment un élément HTML doit être mis en forme.

Par exemple, on peut imaginer la mise en forme suivante : « le titre principal de la page doit s’afficher en rouge et en gros caractères. »

Soit la règle CSS suivante :

h1 {
  color: red;
  font-size: 5em;
}

h1: indique que la mise en forme doit s’appliquer aux éléments <h1> de la page.
entre les accolades {} se trouvent une ou plusieurs “déclarations” sous la forme propriété: valeur ;
exemple, pour déclarer la couleur rouge, soit la déclaration color: red;

Ressources CSS

Il existe plusieurs dizaines de propriétés et de valeurs possibles. Nous en explorerons quelques unes ici, mais il vous sera nécessaire de consulter régulièrement des ressources de référence pour comprendre certaines règles, propriétés ou valeurs : MDN/Référence CSS, W3Schools/Référence CSS

Sélecteurs CSS

Sélecteur : C’est le nom de l’élément HTML situé au début de l’ensemble de règles. Il permet de sélectionner les éléments sur lesquels appliquer le style souhaité (dans le schéma précédent, tous les éléments p). Pour mettre en forme un élément différent, il suffit de changer le sélecteur.

Le sélecteur peut être un élément HTML, ou une classe, ou un identifiant :

p : “tous les éléments p du document HTML”
.important : “tous les éléments de classe .important (quelque soit l’élément qui possède cette classe)”
#job12 : “L’élément identifié par l’identifiant unique #job12 (quelque soit l’élément)”

Le sélecteur peut aussi être une combinaison d’un élément et d’une classe (et/ou identifiant) :
- p.important : “tous les éléments p de classe .important”
- section#job12 : “la section identifiée par #job12”

Ainsi, le sélecteur peut être plus ou moins précis :

p : “tous les éléments p du document HTML”
h1 : “tous les éléments h1 du document HTML”
section p : “tous les éléments p enfants des éléments section”
p.important : “tous les éléments p de classe .important”
section.chapeau p : “tous les éléments p enfants des éléments section de classe .chapeau”
etc.

On peut être encore plus précis en ajoutant un chevron > qui précise le niveau de relation entre deux éléments :
- p > a : “les éléments a (liens) enfant direct d’un ’élément p”
- p a : “tous les éléments a enfant d’un ’élément p quelque soit la «génération»”

Par ailleurs, on peut sélectionner plusieurs éléments à la fois en utilisant la virgule :

p, blockquote : “tous les éléments p et tous les éléments blockquote”
p a, p em : “tous les éléments a et em des éléments p”
section.level2 h2, section.level3 h3 : “tous les éléments h2 des sections de classe .level2 et tous les éléments h3 des sections de classe .level3”
etc.

Ressource pour aller plus loin :

Ajouter des règles CSS à un document HTML

Il existe plusieurs façons d’ajouter des règles CSS à un document HTML:

déclarer les styles directement dans le document HTML avec l’élément HTML <style>. En général, on déclare les styles dans la balise <head>, par exemple :

<head>
   [...]
   <style>
       h1 {
         font-size: 3em;
       }
       p {
         font-size: 1.5em;
         color: darkgrey;
       }
   </style>
</head>

déclarer les styles dans un fichier *.css dédié, séparé du fichier *.html, et associer ce fichier au document HTML avec l’élément HTML <link>

Dans le cas de PinkMypad, nous déclarons des règles CSS dans l’en-tête YAML du pad en markdown.

header-includes: |
  <style>
    body {font-family: mono;}
    h2#lastone {color: black;}
    .blue {color: blue;}
  </style>

Lorsque le pad est converti en document HTML, l’élément <style> et toutes les règles déclarées sont intégrées telles quelles à l’intérieur de la balise <head> du document HTML généré.

Quels règles CSS utiliser ??

Pour personnaliser vos pages PinkMyPad, vous pouvez définir vos propres règles en vous référant aux ressources de MDN ou W3Schools (équivalentes).

Vous pouvez :
1. soit partir d’un élément HTML et identifier les règles CSS qui s’appliquent : W3Schools/explorer un tag HTML
2. soit chercher une propriété ou une valeur CSS et identifier comment l’utiliser : W3Schools/explorer une propriété CSS

Quelques règles à explorer:
- les couleurs en HTML : par nom, par valeur
- les propriétés de tailles: px, em, width, height, font-size, etc.
- les polices de caractères: font-family, font-weight, etc.
- les styles de listes: list-style
- le modèle de boite: écarts, bordures et marges (padding, border, margin)
- etc…

Le principe de hiérarchie et de cascade

Dans une page Pinkmypad (comme dans la plupart des sites web), plusieurs feuilles de styles cohabitent. Ces feuilles déclarent parfois des styles redondantes, voire contradictoires. Dans ce cas, le principe de cascade et de hiérarchie s’applique pour détermine quelle règle sera finalement pris en compte par le navigateur.

Dans la feuille de style suivante, de quelle couleur seront les élément <p> ?

p {color: blue;}
p {color: green;}

Réponse: …

Dans le cas de Pinkmypad, les styles déclarés dans l’en-tête YAML se trouvent “tout en bas de la cascade” (voir la structure HTML de vos pages). Ce sont donc ces styles qui sont pris en compte dans l’affichage.

Par ailleurs, plus la cible d’un style est précise (spécifiant un identifiant ou une classe), plus ce style sera déterminant, même si une règle générale s’applique.

Dans la feuille de style suivante, de quelle couleur seront les éléments <p class="special"> ? De quelle couleur seront les éléments <p>

p {color: blue;}
p.special {color: red;}
p {color: green;}

Réponse: …

Pour explorer et comprendre les principes de hiérarchie et de cascade : MDN/Cascade et hiérarchie

Les templates HTML

Les pages d’un même site web se ressemblent souvent pour conserver une identité graphique et pour offrir une meilleure lisibilité. Elles se ressemblent car elles sont structurées selon un même template (ou “modèle”).

On appelle template un document HTML générique qu’il suffira de “remplir” avec les contenus et les métadonnées de chaque page.

Un template associe le plus souvent une structure HTML et une ou plusieurs feuilles de style CSS, ainsi que des scripts Javascript pour donner de l’interactivité aux pages web.

Ressources:

Il existe de nombreux sites proposant des templates HTML/CSS/JS prêt à l’emploi. Certains sont gratuits, d’autres sont commercialisés. Une recherche Google “template HTML” vous donnera une idée.

Le W3C propose plusieurs templates que vous pouvez utiliser librement : https://www.w3schools.com/w3css/w3css_templates.asp

Bootstrap est un exemple d’outil permettant de construire des templates de page facilement.

On peut remplir ces templates à la main, mais il est très laborieux d’écrire et d’éditer nativement en HTML.

On utilise alors des générateurs de document HTML, qui s’appuient sur différents langages de programmation : PHP, Python, Javascript, etc.

PinkMyPad utilise l’outil Pandoc qui est basé sur le langage Haskell.

Variables

Une variable de template est un élément générique présent dans le template HTML et qui sera remplacé par une valeur ou un contenu du document source au moment de générer la page.

La syntaxe de la variable dépend du langage de programmation utilisé. Avec Pandoc, une variable est entourée par deux $ : $title$ . Dans d’autres langages, une variable sera identifiée par exemple par des accolades {title}, des doubles accolades {{title}}, des guillements simples 'title', etc.

La valeur d’une variable est déterminée par exemple par le couple clé: valeur dans l’en-tête YAML (dans le cas d’une métadonnée).

Ainsi, si l’on a title: Ma toute nouvelle page dans le document source, alors la variable $title$ du template sera remplacée par Ma toute nouvelle page dans le document HTML.

Cas de la variable $content$

La variable $content$ désigne tout le contenu du document source à l’exception de l’en-tête YAML. On ne peut pas intervenir directement dans cette transformation. La structure du document HTML sera donc déterminée par la structure du document source.

Pandoc permet d’utiliser différentes options/extensions pour modifier à la marge le contenu HTML.

Nous n’aborderons pas ces éléments ici, mais vous pouvez en savoir plus en lisant la documentation de Pandoc : Extensions.

Génération d’une page HTML

La génération d’une page HTML à partir du template consiste donc à remplacer toutes les variables définies dans le templates par les valeurs des métadonnées et par le contenu présent dans le document source.

On peut représenter la génération d’une page HTML ainsi :

[Document source (métadonnées + contenu)] x [Template] = PageHTML

Autrement dit, les métadonnées et le contenu du document source sont distribués dans le template pour générer une page HTML. Si l’on modifie le contenu ou une métadonnée, la page HTML est modifiée également.

Reprenons la structure minimale d’un HTML et transformons la en template :

<!DOCTYPE html> 
<html>          
    <head>      
        <meta charset="utf-8"> 
        <title>$title$</title> 
    </head>     
    <body>      
        <h1 class="titre">$title$</h1>
        <p class="auteur">$author$</p>
        $content$ 
    </body>     
</html>

Et le document Markdown suivant :

---
title: Ma toute nouvelle page
author: Nicolas Sauret
---

Que pensez-vous de ma toute nouvelle page ?

Alors la page HTML générée à partir du template et du document sera la suivante

<!DOCTYPE html> 
<html>          
    <head>      
        <meta charset="utf-8"> 
        <title>Ma toute nouvelle page</title> 
    </head>     
    <body>      
        <h1 class="titre">Ma toute nouvelle page</h1>
        <p class="auteur">Nicolas Sauret</p>
        <p>Que pensez-vous de ma toute nouvelle page ?</p>
    </body>     
</html>

Templating sur Pinkmypad

Templates

PinkMyPad comprend pour le moment deux templates différents:

notes.html
cards.html

Sur Gitlab: Le code source des templates est disponible sur Gitlab : voir cards.css et notes.css.

Cela veut dire que selon le choix du layout (c’est-à-dire du template), l’un ou l’autre des templates sera utilisé. Votre page aura toujours la même structure.

Feuilles de styles

Pinkmypad utilise plusieurs feuilles de style en cascades:

pinkmypad.css : règles générales pour toutes les pages pmp
notes.css ou cards.css : règles dédiées au template/layout
pink.css ou blue.css : règles dédiées au thème (palette de couleur)

Ainsi, tous les documents Pinkmypad hérite de la feuille de style générale pinkmypad.css.

À chaque layout correspond une feuille de style dediée : notes.css et cards.css.

Enfin, des feuilles de styles sont dédiées au “thème” qui définit une palette de couleur. Actuellement seule deux thèmes sont disponibles : blue.css et pink.css

À ces styles précédents, s’ajouteront les styles définis dans l’en-tête YAML.

Sur Gitlab: Le code source de ces feuilles de styles sont disponibles sur Gitlab, soit: pinkmypad.css, notes.css, cards.css, pink.css et blue.css.

Personnaliser sa page Pinkmypad

Pour personnaliser votre page, deux possibilités :

ajouter des règles CSS dans l’en-tête de votre pad (voir ci-dessus ou sur la doc de Pink my pad)
créer un nouveau “layout”, c’est-à-dire un nouveau template pour Pinkmypad, avec des règles CSS dédiées. Dans ce cas, l’usage n’est pas automatique, il faudra d’abord faire valider et intégrer votre layout et template par les développeurs de pinkmyapd.

Créer un nouveau layout pour Pink my pad

Mode expert…

Il est déconseillé de partir d’un template trouvé sur Internet. Il est préférable de partir d’un template Pink My Pad existant, et de le modifier progressivement en intervenant sur la structure générale du document HTML et les règles CSS.

Les étapes sont les suivantes :

Préparer un environnement pour travailler en HTML et CSS
Récupérer les sources “en local” sur votre machine
Modifier progressivement la structure et les styles de votre page
Créer le template à partir du résultat obtenu en 3.

1/ Préparer un environnement

Vous aurez besoin d’un éditeur de code et d’un navigateur (Firefox ou Chrome).

Éditeur de texte/code (indispensable)

Les éditeurs de code sont plus ou moins simples selon les fonctionnalités qu’ils offrent. À minima pour ce cours, l’éditeur devra pouvoir colorer les syntaxes html et css (ce qu’ils font tous).

Recommandation : VSCodium (version open source de VS Code de Microsoft)

Voir d’autres éditeurs sous Windows, Max, Linux.

Navigateur

Nous préférerons Firefox ou Chrome car ils disposent d’un mode “développeur” qui permet de modifier les sources d’une page HTMl, et en particulier les feuilles de styles.

2/ Récupérer les sources

Dans un premier temps, nous allons extraire les données et les placer dans un dossier dédié.

Créez un dossier dédié à
Sauvegardez la source HTML de votre page Pinkmypad et placez le fichier dans le dossier créé.
Dupliquez ce fichier de manière à conserver l’original car vous devrez sans doute procéder à plusieurs tests.
Téléchargez le fichier du template et placez le dans le dossier créé.
Téléchargez les fichiers CSS et placez les dans un sous-dossier nommé static.
Ouvrez le fichier source HTML avec votre navigateur (CTRL+O). Si tout va bien, vous devriez pouvoir visualiser votre page Pinkmypad normalement.

3/ Modifier votre page et ses styles

Ouvrez le template et la source HTML dans votre éditeur de code. Localisez dans le template où se trouve la variable $content$ , et identifiez à quoi cela correspond dans la source HTML. Cela veut dire que vous pourrez “travailler” sur tout le reste, c’est-à-dire modifier toute la structure HTML qui ne relève pas du $content$ .
Dupliquer le fichier .css du template original et renommez le selon votre template, par exemple montemplate.css
Associez cette nouvelle feuille de style en remplacant la ligne correspondante sur votre document HTML, par exemple : <link type="text/css" rel="stylesheet" href="/static/notes.css" /> devient <link type="text/css" rel="stylesheet" href="/static/montemplate.css" />. Désormais, en modifiant les règles css de montemplate.css, vous modifierez la mise en forme de votre page.
Vérifiez cela dans votre navigateur
Modifiez la structure HTML à votre guise en éditant simultanément vos styles CSS.

4/ Créez un template

Une fois que vous êtes satisfait avec l’apparence de votre page, vous êtes prêts à créer votre template. Il suffit pour cela de reprendre un template original et de l’adapter en fonction de la structure que vous venez de produire.

Le template ne doit plus contenir de données, mais uniquement des variables.