bidouille/README.md

# Bidouille

Un thème didactique pour Pelican. Il se repose sur le thème `simple` pour les fichier `.html` qui manqueraient.

Le contenu de ce README et petit à petit déplacé sur [le site dédié à ce thème](https://bidouille.computhings.be).

## Particularités du thème

### Page d'accueil

Dans le dossier `pages`, il faut une page avec le paramètre `save_as: index.html` qui deviendra la home page. 

Pour qu'elle soit aussi première entrée du menu principal, il faut qu'elle apparaîsse la première dans l'ordre alphabètique  du dossier `content/pages/`. Pare exemple en y ajoutant un `a. la page.md` ou `1lapage.md` ou `accueil.md`…

### html meta description

Se base sur les éléments `subtitle` et `description` des articles et des pages.

```
---
Title: Ma page ou mon article
Subtitle: Un sous titre qui l'accompagne.
Description: Une description qui la résume succinctement.
Date: 1970-01-01
---
Bla bla bla…
```
- Pour les articles, ces deux éléments sont repris sur les pages qui listent les articles d'une catégorie données.
- Pour les pages, ces deux éléments ne sont pas visibles mais sont tout de même utilisés dans le `meta`.

## ForkAwsome


- [pour télécharger l'archive](https://forkaweso.me/Fork-Awesome/get-started/)
- [pour la liste des icones](https://forkaweso.me/Fork-Awesome/icons/)

Depuis l'archive téléchargée,

- copier `fork-awesome.css` dans `/themes/nom-du-theme/static/css/`
- copier le dossier `fonts` dans `/themes/nom-du-theme/static/`

Dans le template `base.html`, appeler le `fork-awesome.css`.

Les classes du genre `class=fa fa-gnu` sont alors disponibles pour les éléments devant afficher un de ces icones. Par exemple avec `<i class="fa fa-download"></i>`, soit dans les fichiers markdown soit dans les templates html.

Seuls deux fichiers de ForkAwsome sont nécessaires. Je n'ai pas envie de prendre tout leur contenu dans le thème.

Il faudra parfois les mettre à jours.

Une autre piste qui nécessite d'utiliser `git`, c'est de l'inclure en tant que module, mais c'est encore plus technique.


## CSS

### Daisy (à approfondir)

daisy : https://contrib.spip.net/Ordre-d-appel-des-feuilles-de-style ?

reset.css : https://meyerweb.com/eric/tools/css/reset/ … essayé mais viré. 

En utilisant le `reset.css` … le contenu des articles avec du gras ou de l'italique n'avait pas de balise html comme `strong` ou `em` et je n'ai pas compris pourquoi.  Rien qu'un supprimant le chargement de `reset.css` de l'entête html, les balises sont réaparues.

### coloration syntaxique

Pour utiliser la **coloration syntaxique** disponible par défaut dans python/pelican, cela dépend du thème utilisé et des CSS qui l'accompagnent.

Cela fonctionne avec un thème *par défaut* comme `notmyidea` parce que ce thème inclut des fichiers CSS comme…

```bash
/theme/css/main.css
/theme/css/reset.css
/theme/css/pygment.css
/theme/css/typogrify.css
/theme/css/fonts.css
```

Mais si, par exemple il fallait générer un nouveau CSS contenant de quoi faire de la coloration syntaxique, ceci peut aider…

```bash
pygmentize -S default -f html -a .codehilite > styles.css
pygmentize -L style
```
The first command creates a CSS file styles.css with default style. The -f html option specifies the formatter and -a .codehilite option specifies a class in the styles.css file. The second command lists all the styles that comes with Pygments package. 

Comme expliqué [sur cette page](https://georgexyz.com/code-highlight-in-pelican.html)

### Utile pour affiner la sélection d'éléments

Par exemple pour les images, c'est utilisé dans le thème.

- [Sélecteus d'attribut](https://developer.mozilla.org/fr/docs/Web/CSS/Attribute_selectors)
- [CSS Selector Reference](https://www.w3schools.com/cssref/css_selectors.php)

### Mix de Couleurs / transparent

- [How do I apply opacity to a CSS color variable?](https://stackoverflow.com/questions/40010597/how-do-i-apply-opacity-to-a-css-color-variable) = `color-mix`, mais c'est nouveau.

## menu hamburger

Pas utilisé dans le thème, mais au cas où … 

- https://stackoverflow.com/questions/8330559/hover-effects-using-css3-touch-events 
- https://developer.mozilla.org/fr/docs/Web/CSS/:target


## recherche

Pas prévu pour le moment dans le thème.

Je suppose qu'un plugin s'imposera… mais est-ce vraiment nécessaire ?


## feeds, rss, atoms, etc.

Actuellement c'est un peu broullion mais un icône RSS apparaîtra dans le menu `social` pour les pages *catégories* et les *articles*.

À cogiter, voir dans [la doc de pelican](https://docs.getpelican.com/en/latest/themes.html#feeds).


## Open Graphs

À cogiter aussi, voir [the opengraph protocol](https://ogp.me/).

Ou un peu dans [la doc de pelican](https://docs.getpelican.com/en/latest/themes.html#article-html) à propos des artictles.

## Traductions

Actuellement c'est pour un site en français.

Peut-être plus tard…

## Pour les auteur·ice·s

Pas encore fait.

Pour que le(s) auteur·ice·s puissent disposer d'une page personnel, en créant `content/author/xxx.md`, cela ajoutera le contenu à la liste des articles de cette personne **sans** que cette catégorie `author` n'apparaisse dans le menu principal.


## D'autres polices ?

- https://fontlibrary.org/en/catalogue
  - https://fontlibrary.org/en/font/tuffy
  - https://fontlibrary.org/en/font/dark-garden
  - https://fontlibrary.org/en/font/ballpoint-pen
  - https://fontlibrary.org/en/font/artaxerxes
- Iosevka,PragmataPro,Noto Sans Mono Condensed,Consolas,monospace ?


## Table of content

- [Add a Table of Contents using Markdown in Pelican](https://cloudbytes.dev/snippets/add-a-table-of-contents-using-markdown-in-pelican). 
- [Python Markdown - Table of Content](https://python-markdown.github.io/extensions/toc/)
- [Pour en faire une variable utilisable dans les templates](https://github.com/getpelican-plugins/extract_toc) *à essayer un jour*.

Ajouter au `pelicanconf.py`

```python
MARKDOWN = {
    "extension_configs": {
        # Needed for code syntax highlighting
        "markdown.extensions.codehilite": {"css_class": "highlight"},
        "markdown.extensions.extra": {},
        "markdown.extensions.meta": {},
        # This is for enabling the TOC generation
        "markdown.extensions.toc": {"title": ""},
    },
    "output_format": "html5",
}
```

Ajouter dans les articles où il faut une TOC : `[TOC]`.

Un début de custom css…

```css
/* Expériences
*/

article {
    display: grid;
    grid-column-start: 1;
    grid-column-end: 3;
}

article * {
    grid-column: 1;
}

.toc {
    /* Pour la table des matières d'un article (ou d'une page).
    */
    grid-column: 3;
    position: -webkit-sticky;
    position: sticky;
    top: 4em;
    padding: 0em 1.5em;
    background-color: var(--primaire);
    float: right;
    margin-left: 1em;
}

.toc ul {
    padding-left: .5em;
}

.toc li::marker {
    color: var(--deco);
    content: unset;
}

.toc a {
    color: var(--fond);
}

```


## Mais qu'est-ce que je veux vraiment ?

- [x] Que le site soit « responsive ».
  - [x] qu'il soit fonctionnel sur grands écrans avec un affichage **adaptable** en fonction de la résolution.
  - [x] que les pages / articles soient imprimable SANS les menus.
  - [x] qu'il soit fonctionnel sur bidulephone
  - [ ] qu'une page « fcktmrtphn » apparaîsse à la place ou en plus ?
- [x] Que les images soient le plus simple à ajouter, soit avec la balise `img` soit avec d'autres mécanismes plus simple associés au Markdown
- [x] Qu'il y ait un `favicon`
- [ ] Qu'il y ait une page `auteurs` même si il n'y en a qu'un seul, et donc prévoir qu'il y en ait plusieurs *(mais c'est pas pour moi)*.
- [x] Que la structure du `output` reflète le plus possible la structure du `content`.
- [ ] Une [404](https://docs.getpelican.com/en/latest/tips.html#custom-404-pages)
- [x] Une table des matières pour les longs articles *(en tout cas, pas quand il n'y a qu'un ou deux « sous titres »)*
- [x] Des ancres pour la TOC mais aussi pour avoir de quoi pointer vers un sous titre et pas toute la page pour partager un lien vers un sous titre de la page.
- [x] Qu'il y ait un menu de pagination fonctionnel.

## Qu'est-ce que je devrais encore explorer ?

- [ ] Que je me décide à propos des `catégories` et des `tags` *(mots-clés)*.
- [ ] La notion des `archives`.
- [ ] La notion de `drafts` et/ou de `hidden` *(par exemple pourquoi c'est dans le `output` si c'est des brouillons ou du contenu caché)* ?
- [ ] Le multilinguisme comme dans le fichier `translations.html` du theme simple.

## À l'occasion j'aimerais aussi…

- [ ] les cases à cocher en markdown/html
- [ ] les bulles d'info comme danc HedgeDoc `:::info` en markdown/html
- [ ] pouvoir basculer en clair/sombre automatiquement (ou à la demande). S'informer sur la balise html `<meta name="color-scheme" content="dark light" />
` [ici](https://developer.mozilla.org/fr/docs/Web/HTML/Element/meta).
- [ ] dans le cas d'un thème sombre il faut d'autre `highlight` pour le `code` parce que `highlight.css` est pour un thème clair.
- [ ] que les mises à jours du thème s'intègrent automatiquement au deux sites sur lesquels je l'utilise et donc … explorer `pelican-themes`.