12. Aloje el sitio web HTML en GitHub

Fue el propio Gemini quien se ofreció a alojar el sitio HTML producido por sus dos guiones en GitHub¹. No sabía que eso fuera posible. GitHub es un sitio que alberga proyectos de desarrollo. Exportar cursos de programación allí parece natural.

Primero necesitas tener una cuenta GitHub. Si es necesario, créalo.

Conéctese a su cuenta GitHub:

En [2], sus repositorios existentes si los tiene;
En [3], cree un nuevo repositorio GitHub ;

En [1], utilice el nombre que introdujo en [config.py] :


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

En [2], también puede introducir lo mismo que en [config.py] :

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",`

En [3], confirme la creación de su repositorio GitHub;

Es aconsejable que cada repositorio GitHub cree un archivo [README.md] que se mostrará en lugar de la pantalla anterior. Debe estar escrito en MarkDown, lo que no es fácil. Así que escribiremos un fichero de texto con lo que queremos ver en README. Luego pediremos el IA para darnos el README.md correspondiente.

El archivo de texto [readme.txt] será el siguiente:

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.

El indicador Gemini es el siguiente:

En [1], el archivo adjunto [readme.txt] ;
En [2], el prompt ;

Copia la respuesta que te da Gemini en el archivo [README.md] de tu carpeta de trabajo. Aquí está la respuesta que Gemini me dio:

# 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 un README que me dio. Eso es porque Gemini conoce muy bien este proyecto y llevamos semanas trabajando en él. Probablemente obtendrás un [README.md] menos detallado.

Ahora volvamos a nuestro archivo de trabajo:

En [2], el fichero README que acaba de modificar;
En [1], el archivo [deploy.txt] explica cómo exportar su sitio HTML a su repositorio GitHub;

El contenido del fichero [deploy.txt] es el siguiente:

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

Esta es la secuencia de comandos que exportará su sitio HTML a su repositorio GitHub. Deberá modificar la línea 7 con el URL de su propio repositorio GitHub, presente en el fichero [config.py] :

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

Debe comprobar también otro URL en el fichero [robots.txt] :

El contenido del fichero [robots.txt] es el siguiente:


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

En la línea 3, introduzca el URL de su sitio, el mismo que en el archivo [config.py] :


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

Le archivo [robots.txt] no se utiliza cuando el sitio se construye localmente, pero sí cuando se aloja en GitHub.

El conjunto de comandos [deploy.txt] utiliza un software llamado Git. Necesitas instalarlo [Git - Instalación para Windows].

Una vez hecho esto, comprueba el archivo llamado [.gitignore] en tu carpeta de trabajo. Le dice a Git qué archivos debe ignorar. Mi archivo [.gitignore] es el siguiente:

# 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

Es extremadamente sencillo. Ignora todos los archivos (línea 2) excepto el archivo [README.md] (línea 5). GitHub está diseñado para alojar proyectos de desarrollo. En general, todo el proyecto de desarrollo se exporta a GitHub. Nosotros simplemente queremos exportar un sitio HTML, no un proyecto de desarrollo. El único archivo que queremos exportar a nuestro repositorio GitHub es el archivo [README.md] que explica a los visitantes lo que contiene nuestro sitio HTML.

Ahora, en su terminal, escriba la siguiente secuencia de comandos en el orden indicado por [deploy.txt] hasta el comando 8. No ejecute el comando 9 por el momento.


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'.

Ctrl-clic en el URL en la línea 17. Esto le llevará a su repositorio GitHub:

En [1], el URL de su depósito GitHub ;
En [2], el nuevo README.md ;

Ahora vamos al comando 9 en el archivo [deploy.txt]. Esto exporta el sitio HTML a 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/

Ctrl-clic en el URL en la línea 21. Esto le llevará a su nuevo sitio HTML en GitHub :

En [1], vemos que está mostrando un sitio web en GitHub ;

Es extremadamente fácil cometer un error al ejecutar comandos [deploy.txt]. Luego es difícil volver atrás porque Git guarda la memoria de lo que hiciste (mal). Para empezar desde cero, consulta el archivo :

En [1], elimine la carpeta [.git];

Luego vuelve a PyCharm y repite la serie de comandos desde [deploy.txt].

¿Qué debe hacer si modifica su Documento ODT / DOCX? Haga las 3 cosas siguientes:

convierte tu Documento ODT / DOCX de nuevo con [convert] ;
construir el sitio HTML con [build] ;
exporte el sitio HTML a GitHub con el comando [python -m mkdocs gh-deploy]. Este comando es suficiente siempre que no modifique el archivo [README.md]. Si modifica el archivo [README.md], tendrá que ejecutar algunos comandos más:

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

Si sólo ha modificado README, sólo son necesarios los comandos 1, 3 y 4. El comando 5 es inútil si ya ha desplegado el sitio HTML y no se ha movido desde entonces.

¿Qué debes hacer si quieres empezar de cero porque las cosas han ido mal? Puedes borrar tu repositorio GitHub y rehacer todas las operaciones del capítulo 12. El option para borrar un repositorio GitHub está bien escondido :

En [1], vaya a los parámetros de configuración del repositorio ;

Vaya a la parte inferior de la página [configuración]. Allí encontrarás el botón para borrar tu repositorio [2].

Nota a pie de página para GitHub ↩