LHTML+ lhtml-site

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.

Il vous faut : lhtml-site installé et un site qui se construit ; pour GitHub Pages, un compte GitHubDurée : 15 à 30 minVous obtenez : votre site à une adresse publique

Partout : copier .site/

  • Sans serveur : ouvrez .site/index.html depuis 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

  1. Placez le projet dans un dépôt GitHub : commitez configure.yaml et src/, pas ce qu'écrit la construction. Écrivez d'abord un fichier .gitignore à côté de configure.yaml, qui écarte ce que produit la construction :

    /.site/
    /.structure/
    /.verification/
    /.layout/
    /.feedback/
    /code/
    /slides.pdf
    /images/
    

    .layout/ est le rapport de lhtml-site --layout ; .feedback/ garde les commentaires écrits sur les pages pendant lhtml-site --serve ; slides.pdf et images/ sont ce qu'écrit le thème slides-pdf à côté de configure.yaml ; code/ contient les dépôts clonés par le plugin code_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.

  2. Ajoutez ce fichier, qui construit le site à chaque push sur main et 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
    
  3. 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 aussi cache_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 ligne run : pip install lhtml-site 'pagefind[extended]' && lhtml-site && python -m pagefind --site .site.
  • Avec une cible pdf (thème slides-pdf), le workflow a besoin de Playwright et de son Chromium : remplacez la ligne run par pip 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-site lancé 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_url ne 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.

Construit avec lhtml-site, thème docs. Fait partie de ScholarTools.