12. Die Website HTML auf GitHub hosten

Es war Gemini selbst, der mir angeboten hat, die von seinen beiden Skripten erstellte Website HTML auf GitHub zu hosten¹. Ich wusste nicht, dass das möglich ist. GitHub ist eine Website, die Entwicklungsprojekte beherbergt. Programmierkurse dorthin zu exportieren, erscheint natürlich.

Sie müssen zunächst ein Konto haben GitHub. Erstellen Sie es bei Bedarf.

Melden Sie sich bei Ihrem Konto GitHub an:

In [2] Ihre bestehenden Repositories, falls Sie welche haben;
Legen Sie in [3] ein neues Depot GitHub an;

Verwenden Sie in [1] den Namen, den Sie in [config.py] gesetzt haben:


  "repo_url": "https://github.com/stahe/word-odt-vers-html-janv-2026",

In [2] können Sie auch das Gleiche wie in [config.py] eintragen:

1	`"site_description": "Convertir un document Word ou ODT vers un site statique HTML à l'aide de les IA Gemini 3 et ChatGPT 5.2",`

Bestätigen Sie in [3] die Erstellung Ihres Depots GitHub ;

Es ist ratsam, für jede GitHub-Einreichung eine Datei [README.md] zu erstellen, die anstelle des obigen Bildschirms angezeigt wird. Sie soll in MarkDown geschrieben werden, eine nicht ganz einfache Sache. Wir werden also eine Textdatei schreiben, in der drin steht, was wir in README sehen möchten. Dann fragen wir der IA uns den passenden README.md zu geben.

Die Textdatei [readme.txt] wird wie folgt aussehen:

On se propose dans cet article de mettre à disposition du lecteur un convertisseur Python de documents Word ou ODT vers un site statique HTML.

Ce convertisseur a été construit par l’IA Gemini 3.

Lorsque le document ODT convient, le convertisseur produit un site HTML via MkDocs qui a l'aspect professionnel des sites produits par Pandoc.

J’ai utilisé  Gemini 3 avec un abonnement pro.

Der Prompt in Gemini lautet dann wie folgt:

In [1] wird die angehängte Datei [readme.txt] ;
In [2] wird der Prompt ;

Kopieren Sie die Antwort, die Gemini Ihnen gibt, in die Datei [README.md] in Ihrem Arbeitsordner. Hier ist die Antwort, die Gemini mir gegeben hat:

# Convertisseur Word/ODT vers Site HTML (MkDocs)

🔗 **[Voir le site de démonstration généré](https://stahe.github.io/word-odt-vers-html-janv-2026/)**

---

## 📝 Description

On se propose dans ce projet de mettre à disposition du lecteur un convertisseur Python de documents Word ou ODT vers un site statique HTML.

Lorsque le document ODT convient, le convertisseur produit un site HTML via **MkDocs** qui a l'aspect professionnel des sites produits par Pandoc.

## 🤖 Contexte de création

Ce convertisseur a été entièrement construit par l’IA **Gemini 3** (avec un abonnement pro). Il est le résultat d'itérations successives pour gérer finement la structure des documents ODT (OpenDocument Text).

## ✨ Fonctionnalités

Le script `convert.py` effectue les actions suivantes :

* **Conversion ODT vers Markdown** : Analyse le fichier `.odt` (XML) pour en extraire la structure.
* **Gestion des Titres** : Génère automatiquement la Table des Matières (TOC) et la navigation latérale.
* **Blocs de Code** : Détection automatique des langages, coloration syntaxique et **gestion précise de la numérotation des lignes** (attributs `start-value`).
* **Listes** : Support des listes à puces et numérotées avec indentation correcte.
* **Mise en forme** : Support du *gras*, *italique*, *souligné* et du *surlignage* (avec respect des couleurs d'origine).
* **Images** : Extraction et intégration automatique des images contenues dans le document.
* **Configuration** : Personnalisation via un fichier `config.py` (Bas de page, Google Analytics, etc.).

## 🚀 Installation

### Prérequis

* Python 3.x
* Les bibliothèques suivantes :

```bash
pip install odfpy unidecode mkdocs mkdocs-material

```

### Structure du projet

Assurez-vous d'avoir les fichiers suivants :

* `convert.py` : Le script de conversion.
* `config.py` : Votre fichier de configuration.
* `votre-document.odt` : Le document source.

## 💻 Utilisation

1. **Conversion**
Lancez le script en indiquant le fichier ODT source et le fichier de configuration :
```bash
python convert.py votre-document.odt config.py

```


*Cela va générer un dossier `docs/` contenant les fichiers Markdown et un fichier `mkdocs.yml`.*
2. **Prévisualisation**
Pour voir le site en local :
```bash
mkdocs serve

```


3. **Génération**
Pour construire le site statique (dossier `site/`) :
```bash
mkdocs build

```



## ⚙️ Configuration (`config.py`)

Le fichier `config.py` permet de contrôler l'apparence du site :

* **mkdocs** : Paramètres généraux du site (titre, description, thème Material).
* **footer** : Code HTML complet pour personnaliser le pied de page.
* **code** : Règles de détection des langages pour la coloration syntaxique.
* **extra** : Configuration de Google Analytics (GA4).

## 📄 Licence

Ce cours tutoriel écrit par **Serge Tahé** est mis à disposition du public selon les termes de la :
*Licence Creative Commons Attribution – Pas d’Utilisation Commerciale – Partage dans les Mêmes Conditions 3.0 non transposé.*

Es ist ein README sehr ausführlichen Bericht, den er mir zur Verfügung gestellt hat. Das liegt daran, dass Gemini dieses Projekt, an dem wir seit Wochen arbeiten, sehr gut kennt. Sie werden wahrscheinlich ein weniger detailliertes [README.md] bekommen.

Nun zurück zu unserer Arbeitsmappe:

In [2] die Datei README, die Sie gerade bearbeitet haben ;
In [1], die Datei [deploy.txt] erklärt, wie Sie Ihre Website HTML in Ihr Repository GitHub exportieren können;

Der Inhalt der Datei [deploy.txt] ist wie folgt:

git init
git branch -M main
# vérifier .gitignore avant !
git add .
# premier commit
git commit -m "Initial commit: Source MkDocs"
git remote add origin https://github.com/stahe/word-odt-vers-html-janv-2026.git
git push -u origin main
python -m mkdocs gh-deploy

Dies ist die Befehlsfolge, die Ihre Website HTML in Ihr Repository GitHub exportieren wird. Sie müssen Zeile 7 mit dem URL aus Ihrem eigenen Repository GitHub ändern, das in der Datei [config.py] vorhanden ist:

1	`"repo_url": "https://github.com/stahe/word-odt-vers-html-janv-2026",`

Sie sollten prüfen auch eine andere URL in der Datei [robots.txt]:

Der Inhalt der Datei [robots.txt] ist wie folgt:


User-agent: *
Allow: /
Sitemap: https://stahe.github.io/word-odt-vers-html-janv-2026/sitemap.xml

Setzen Sie in Zeile 3 den URL Ihrer Website ein, denselben wie in der Datei [config.py] :


        # URL de publication du site (ex: GitHub Pages)
        "site_url": "https://stahe.github.io/word-odt-vers-html-janv-2026/",

Le Datei [robots.txt] wird beim lokalen Aufbau der Website nicht verwendet, wird aber verwendet, wenn sie auf GitHub gehostet wird.

Die Befehlsfolge von [deploy.txt] verwendet eine Software namens Git. Sie müssen es installieren [Git - Install for Windows].

Wenn du das getan hast, überprüfe die Datei mit dem Namen [.gitignore] in deinem Arbeitsordner. Sie teilt Git mit, welche Dateien es ignorieren soll. Meine Datei [.gitignore] sieht wie folgt aus:

# 1. On ignore TOUS les fichiers et dossiers du projet
*

# 3. On fait une exception (!) pour le seul fichier que vous voulez garder
!README.md

Er ist extrem einfach. Wir ignorieren alle Dateien (Zeile 2) außer der Datei [README.md] (Zeile 5). GitHub ist dafür gedacht, Entwicklungsprojekte zu hosten. Normalerweise wird das gesamte Entwicklungsprojekt nach GitHub exportiert. Wir wollen lediglich eine HTML-Website exportieren, kein Entwicklungsprojekt. Die einzige Datei, die wir in unser Repository GitHub exportieren wollen, ist die Datei [README.md], die den Besuchern erklärt, was unsere Website HTML enthält.

Geben Sie nun in Ihrem Terminal die folgende Befehlsfolge in der durch [deploy.txt] angegebenen Reihenfolge ein, bis hin zu Befehl 8. Führen Sie Befehl 9 noch nicht aus.


PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git init
Initialized empty Git repository in C:/Data/st-2025/GitHub Pages/word-odt-vers-html/v2/.git/
PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git branch -M main
PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git add .
PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git commit -m "Initial commit: Source MkDocs"
[main (root-commit) 7cba5b1] Initial commit: Source MkDocs
 1 file changed, 89 insertions(+)
 create mode 100644 README.md
PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git remote add origin https://github.com/stahe/word-odt-vers-html-janv-2026.git
PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> git push -u origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 1.70 KiB | 1.70 MiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://github.com/stahe/word-odt-vers-html-janv-2026.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Machen Sie einen Ctrl-Klick auf den URL der Linie 17. Dies wird Sie zu Ihrem Depot GitHub bringen:

In [1] wird der URL Ihrer Einreichung GitHub ;
In [2] wurde das neue README.md ;

Nun wenden wir uns dem Befehl 9 in der Datei [deploy.txt] zu. Dieser Befehl exportiert die Website HTML nach GitHub :


PS C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2> python -m mkdocs gh-deploy
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2\site
INFO    -  Doc file 'les-exemples.md' contains a link '#_Les_exemples', but there is no such anchor on this page.
INFO    -  Documentation built in 1.79 seconds
WARNING -  Version check skipped: No version specified in previous deployment.
INFO    -  Copying 'C:\Data\st-2025\GitHub Pages\word-odt-vers-html\v2\site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 91, done.
Counting objects: 100% (91/91), done.
Delta compression using up to 8 threads
Compressing objects: 100% (85/85), done.
Writing objects: 100% (91/91), 1.64 MiB | 2.01 MiB/s, done.
Total 91 (delta 9), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (9/9), done.
remote: 
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/stahe/word-odt-vers-html-janv-2026/pull/new/gh-pages
remote: 
To https://github.com/stahe/word-odt-vers-html-janv-2026.git
 * [new branch]      gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://stahe.github.io/word-odt-vers-html-janv-2026/

Machen Sie einen Ctrl-Klick auf den URL in Zeile 21. Dies wird Sie zu Ihrem neuen Standort HTML auf GitHub bringen:

In [1] sehen wir, dass Sie eine Website web auf GitHub anzeigen;

Es ist extrem leicht, bei der Ausführung der Befehle von [deploy.txt] einen Fehler zu machen. Dann ist es schwierig, wieder zurückzugehen, da Git sich merkt, was du (falsch) gemacht hast. Um neu anzufangen, sehen Sie sich den Arbeitsordner :

Löschen Sie in [1] den Ordner [.git] ;

Kehren Sie dann zu PyChar zurückm und wiederholen Sie die Befehlsreihe von [deploy.txt].

Was tun Sie, wenn Sie Ihr Dokument ODT / DOCX ändern? Führen Sie die folgenden drei Dinge aus:

konvertieren Sie Ihr Dokument ODT / DOCX erneut mit [convert] ;
bauen Sie die Seite HTML mit [build] ;
exportieren Sie die Website HTML auf GitHub mit dem Befehl [python -m mkdocs gh-deploy]. Dieser Befehl reicht aus, solange Sie die Datei [README.md] nicht ändern. Wenn Sie die Datei [README.md] ändern, müssen Sie etwas mehr Befehle ausgeben :

git add README.md
# commit
git commit -m "modif README"
git push -u origin main
python -m mkdocs gh-deploy

Wenn Sie nur den README geändert haben, sind nur die Befehle 1, 3, 4 erforderlich. Der Befehl 5 ist unnötig, wenn Sie die Website HTML bereits eingesetzt haben und sie sich seitdem nicht verändert hat.

Was können Sie tun, wenn Sie noch einmal von vorn anfangen wollen, weil die Dinge aus dem Ruder gelaufen sind? Sie können Ihr Depot GitHub löschen und alle Operationen aus dem Kapitel wiederholen 12. Der option zum Löschen eines GitHub Depots ist gut versteckt :

Gehen Sie in [1] zu den Konfigurationseinstellungen des Depots ;

Gehen Sie ganz nach unten auf die Seite der [settings]. Dort finden Sie die Schaltfläche zum Löschen Ihres Depots [2].

Fußnote zu GitHub ↩