Mettre en ligne
Le site, c'est le répertoire .site/ : des fichiers statiques, sans base de données, sans programme
à exécuter sur le serveur. Copiez-le n'importe où, du moment que les fichiers sont servis. Ses pages
se lient entre elles par des liens relatifs : le site fonctionne à n'importe quelle adresse, à la
racine d'un serveur ou loin en dessous.
Partout : copier .site/
- Sans serveur : ouvrez
.site/index.htmldepuis le disque, ou envoyez le répertoire dans un zip. - Un serveur accessible en ssh (souvent le cas d'une université), construisez, puis copiez :
lhtml-site rsync -av --delete .site/ me@server:/var/www/my-course/
La barre oblique après .site/ copie son contenu, pas le répertoire lui-même ; --delete retire
les fichiers que le site n'a plus. Sur un serveur d'université, le répertoire est souvent
~/public_html/, servi à https://www.mon-universite.fr/~moi/ : demandez à votre service
informatique. Un programme comme FileZilla copie aussi les fichiers.
.site/ est caché, comme tout nom qui commence par un point : Cmd+Maj+. l'affiche dans le Finder
de macOS, Affichage > Éléments masqués dans l'explorateur de Windows.
GitHub Pages
-
Placez le projet dans un dépôt GitHub : commitez
configure.yamletsrc/, pas ce qu'écrit la construction. Écrivez d'abord un fichier.gitignoreà côté deconfigure.yaml, qui écarte ce que produit la construction :/.site/ /.structure/ /.verification/ /.layout/ /.feedback/ /code/ /slides.pdf /images/
.layout/est le rapport delhtml-site --layout;.feedback/garde les commentaires écrits sur les pages pendantlhtml-site --serve;slides.pdfetimages/sont ce qu'écrit le thèmeslides-pdfà côté deconfigure.yaml;code/contient les dépôts clonés par le plugincode_include.py. Une ligne pour un fichier que vous n'avez pas ne gêne pas.Vous débutez avec git ? GitHub Desktop le fait avec des boutons : File > Add local repository, choisissez le répertoire du projet (il propose de créer le dépôt), Commit to main, puis Publish repository ; après chaque modification, Commit et Push origin.
-
Ajoutez ce fichier, qui construit le site à chaque push sur
mainet le publie :# .github/workflows/pages.yml on: {push: {branches: [main]}, workflow_dispatch: {}} permissions: {contents: read, pages: write, id-token: write} jobs: deploy: runs-on: ubuntu-latest environment: github-pages steps: - uses: actions/checkout@v7 - uses: actions/setup-python@v7 with: {python-version: '3.12'} - run: pip install lhtml-site && lhtml-site - uses: actions/upload-pages-artifact@v5 with: {path: .site} - uses: actions/deploy-pages@v5
-
Dans les paramètres du dépôt, rubrique Pages, choisissez GitHub Actions comme source.
Après le push suivant, l'onglet Actions montre la construction, et le site est à
https://me.github.io/my-course/ (votre compte, puis le nom du dépôt).
- Avec des vidéos (
cache_video_directory), commitez aussicache_video/: la construction réutilise les vidéos converties, et n'a pas besoin de ffmpeg sur GitHub. - Avec le thème
docs, ajoutez l'index de recherche à la lignerun:pip install lhtml-site 'pagefind[extended]' && lhtml-site && python -m pagefind --site .site. - Avec une cible
pdf(thèmeslides-pdf), le workflow a besoin de Playwright et de son Chromium : remplacez la lignerunparpip install "lhtml-site[pdf]" && python -m playwright install --with-deps --only-shell chromium && lhtml-site.
La page 404 (thème docs)
Le thème docs peut écrire un 404.html, la page affichée pour une adresse qui ne mène nulle part.
Il a besoin de savoir où le site est servi, dans configure.yaml :
base_url: '/my-course/'
/ à la racine d'un serveur, /my-course/ pour https://me.github.io/my-course/,
/~moi/my-course/ pour une page d'université, ou une URL entière terminée par /. Le 404.html
fonctionne alors à n'importe quelle profondeur. GitHub Pages et Netlify le servent tout seuls ; pour
nginx : error_page 404 /my-course/404.html;, pour Apache (un fichier .htaccess) :
ErrorDocument 404 /my-course/404.html.
Sans base_url, et avec les autres thèmes, il n'y a pas de 404.html : le serveur affiche le sien.
Plus de détails dans le thème docs
(en anglais).
Recherche (thème docs)
Le champ de recherche a besoin de son index, construit après le site :
lhtml-site python -m pip install 'pagefind[extended]' python -m pagefind --site .site
Lancez la ligne pip dans un environnement virtuel : hors d'un tel environnement, Homebrew et les
Python système récents la refusent. Avec Node.js, npx pagefind --site .site fait la même chose.
Chaque construction remplace .site/, et son index avec : relancez pagefind après chaque
construction. La recherche fonctionne quand le site est servi en http, pas depuis un fichier ouvert
sur le disque. Pour l'essayer, servez le répertoire tel quel, sans le reconstruire :
python3 -m http.server -d .site, puis http://localhost:8000/.
En cas de problème
- L'onglet Actions montre une construction en rouge : ouvrez-la, l'étape qui échoue dit
pourquoi ; le même
lhtml-sitelancé sur votre ordinateur montre en général la même erreur. - La page 404 n'a pas de style, ou ses liens ne mènent nulle part :
base_urlne correspond pas à l'adresse du site ; il doit commencer et finir par/. - Le site fonctionne depuis le disque mais pas en ligne : vérifiez que vous avez copié le contenu
de
.site/, pas le répertoire lui-même (la barre oblique de.site/).
Ensuite : Thèmes, pour changer l'apparence du site.