7. Les fichiers de configuration des convertisseurs
 |
Le fichier de configuration [config.py] rassemble les informations qui peuvent changer d’un document à l’autre. Il utilise 6 autres fichiers de configuration. On a rassemblé dans ces derniers les paramètres les plus susceptibles de changer lorsqu’on passe d’un document à l’autre pour la conversion.
Le fichier [config.py] importe le contenu des 6 autres fichiers de configuration :
from config_urls import URLS
from config_texts import TEXTS
from config_code import CODE
from config_styles import STYLES
from config_colors import COLORS
from config_presentation import PRESENTATION
config_urls
Ce fichier rassemble les trois URL de la configuration [config.py]. Celles-ci changent avec chaque document.
URLS = {
"site_url": "https://stahe.github.io/word-odt-vers-html-janv-2026/",
"repo_url": "https://stahe.github.io/word-odt-vers-html-janv-2026",
"author_site": "https://tahe.developpez.com",
}
- ligne 2 : l’URL du site web où vous allez déployer le site HTML produit par le convertissseur ;
- ligne 3 : l’URL de votre dépôt Git (voir paragraphe 12) ;
- ligne 4 : le site web du créateur du site web. Cette URL est placée dans le bas des pages du site web. Peut être vide.
config_texts
Ce fichier rassemble les textes de [config.py] susceptibles de changer lors d’un changement de langue du site HTML généré.
TEXTS = {
"home_label": "Accueil",
"site_name": "Convertir un document Word ou ODT vers un site statique HTML compatible MkDocs avec les IA Gemini 3 et ChatGPT 5.2",
"site_description": "Convertir un document Word ou ODT vers un site statique HTML compatible MkDocs avec les IA Gemini 3 et ChatGPT 5.2",
"toggle_to_dark": "Passer en mode sombre",
"toggle_to_light": "Passer en mode clair",
"footer_license_sentence": (
"Ce cours-tutoriel écrit par <strong>Serge Tahé</strong> est mis à disposition du public selon les termes de la\n"
" <em>Licence Creative Commons Attribution – Pas d’Utilisation Commerciale –\n"
" Partage dans les Mêmes Conditions 3.0 non transposé</em>.\n"
),
"copy_label": "Copier",
"copy_copied_label": "Copié",
}
- ligne 2 : le nom du premier lien dans la table des matières. Son contenu rassemble tout ce qui est dans le document avant le premier titre de niveau 1 (Titre 1). C’est le début du document ;
- ligne 3 : le titre du document. Il est affiché dans le bandeau supérieur du site web généré ;
- ligne 4 : également le titre du document à destination cette fois des moteurs de recherche ;
- lignes 5-6 : les bulles affichées lorsqu’on passe la souris sur l’icône présente dans la barre supérieure du site pour passer d’un mode clair à un mode sombre ou vice-versa ;
- lignes 7-11 : la licence du site. Elle est affichée dans le pied de page du site généré ;
- lignes 12-13 : le code affiché sur le site l’est, accompagné d’un bouton qui permet de copier le code dans le presse-papiers. La ligne 12 est le libellé du bouton avant copie, la ligne 13 le libellé lorsque le code a été copié ;
Voilà à quoi ressemble ce fichier pour une version anglaise du document :
TEXTS = {
"home_label": "Welcome",
"site_name": "Convert a Word or ODT document into a static HTML website using Gemini 3 and ChatGPT 5.2",
"site_description": "Convert a Word or ODT document into a static HTML website using Gemini 3 and ChatGPT 5.2 AI",
"toggle_to_dark": "Switch to dark mode",
"toggle_to_light": "Switch to light mode",
"footer_license_sentence": (
'This tutorial written by <strong>Serge Tahé</strong> is made available to the public under the terms of the\n'
'<em>Creative Commons Attribution – Non-Commercial –\n'
'ShareAlike 3.0 Unported</em>.'
),
"copy_label": "Copy",
"copy_copied_label": "Copied",
}
config_styles
Ce fichier sert à donner le nom du style du titre du document. Pour un document DOCX, c’est généraleme,t « Titre » mais pour un document ODT, ça change avec chaque document.
STYLES = {
"style_names": [
"P1"
]
}
- ligne 2 : [styles_names] est un tableau. On peut y mettre les noms des styles que peut avoir le titre du document ;
- ligne 3 : le document [word-odt-vers-html-janv-2026.odt] a un titre avec le style P1 ;
config_code
Les blocs de code dans le document DOCX ou ODT peuvent être trouvés sous deux formes :
- du code enrichi (couleurs, gras, italiques, …). Dans ce cas, il est copié tel quel dans le site HTML ;
- du code brut (plain text). Dans ce cas, on donne des indications aux convertisseurs pour qu’ils trouvent eux-même le langage utilisé dans le bloc de code. Pour cela, on lui donne des mots clés :
CODE = {
# Automatic language detection rules based on content
"detection_rules": {
"csharp": [
"using", "Console.WriteLine", "public static void Main", "WebMethod",
"TryParse", "EventArgs", "String.Format", "System.Web.Services"
],
"java": [
"System.out.println", "public static void main(String", "package",
"JUnitTest", "Class.forName", "PreparedStatement", "private static void",
"private void", "getAgendaMedecinJour", "@PostConstruct", "@ResponseBody",
"@RequestMapping", "getMedecin", "@Entity", "@Autowired", "@Bean",
"Serializable", "getClient", "getCreneau", "getRv", "PostAjouterRv",
"PostSupprimerRv", "@EnableJpaRepositories", "@Component", "getAgendaMedecinJour",
"getResponse", "getMessagesForException", "getBase64", "ajouterRv",
"Reponse", "getPartialViewAgenda", "setModelforAgenda", "ActionContext",
"getActionContext", "PostLang", "PostUser", "PostGetAgenda", "@NotNull",
"@EnableAutoConfiguration", "HttpSecurity"
],
"html": [
"<html>", "</div>", "<body>", "<script>", "href=", "<span>", "<p>",
"<h2>", "<form", "<table", "<input"
],
"sql": [
"SELECT", "INSERT INTO", "UPDATE", "DELETE FROM", "WHERE",
"CREATE TABLE", "AlTER TABLE"
],
"python": [
"def", "import", "print(", "from"
],
"xml": [
"<?xml", "<project", "<version>", "<configuration>", "<build>",
"<dependency>", "<properties>", "<configuration>", "<start-class>"
],
"javascript": [
"use strict", "console.log", "let", "constructor", "async", "export"
],
"php": [
"<?php", "declare", "require"
],
"vbscript": [
"Option", "Dim", "Explicit"
],
"markdown": [
"# ", "## ", "### ", "**", "__", "![", "](" # Typical Markdown markers
],
},
}
Encore une fois, ces règles de détection ne s’appliquent qu’aux blocs de code en « plain text » et pas aux blocs de code enrichi. Si vous découvrez sur votre site que des blocs de code n’ont pas été colorés, c’est là qu’il faut venir.
Pour chaque langage on indique les chaînes de caractères qui permettent d’identifier ce langage. Certains mots clés peuvent se retrouver dans divers langages. Le convertiseur sélectionne le langage pour lequel il a trouvé le plus de mots clés. Le principe est simple : vous regardez vos codes, sélectionnez des mots clés caractéristiques et vous les mettez dans ces lignes pour le bon langage. Notez que vous ne pouvez pas mettre n’importe quoi comme nom de langage : il faut utiliser les noms reconnus par MkDocs ;
config_presentation
Ce fichier fixe l’apparence de différents éléments du site web généré. Ce n’est pas quelque chose qu’on est amené à changer souvent :
PRESENTATION = {
# -------------------------------------------------------------------------
# Document title
# -------------------------------------------------------------------------
"document_title": {
"font_size": "28px",
"font_weight": "bold",
"margin_bottom": "1em",
"line_height": "1.2"
},
# -------------------------------------------------------------------------
# Rich code blocks
# -------------------------------------------------------------------------
"code": {
"rich_line_height": "12px",
"rich_font_family": "Consolas, 'Courier New', monospace",
"rich_font_size": "15px"
},
# -------------------------------------------------------------------------
# Copy button
# -------------------------------------------------------------------------
"copy_button": {
"container": "position: relative;",
"btn": (
"position:absolute; top:.5rem; right:.5rem; "
"display:inline-flex; align-items:center; justify-content:center; "
"gap:.35rem; "
"padding:.25rem .6rem; "
"font-size:.72rem; font-weight:600; letter-spacing:.01em; "
"line-height:1.2; "
"border-radius:999px; "
"box-shadow:0 1px 2px rgba(0,0,0,.10); "
"backdrop-filter:saturate(180%) blur(6px); "
"cursor:pointer; user-select:none; "
"transition:transform .08s ease, box-shadow .12s ease, background .12s ease; "
"z-index:5;"
),
"btn_hover": (
"box-shadow:0 3px 10px rgba(0,0,0,.18); "
"transform:translateY(-1px);"
),
"btn_copied": "opacity:.85;"
},
# -------------------------------------------------------------------------
# Images
# -------------------------------------------------------------------------
"images": {
"shadow": {
"enabled": True,
"border_radius": "8px"
}
},
# -------------------------------------------------------------------------
# Frame / header border
# -------------------------------------------------------------------------
"frame": {
"header_top_border_width": "4px"
}
}
Si vous le souhaitez, vous pouvez modifier l’apparence :
- lignes 5-10 : du titre du document ;
- lignes 15-19 : des lignes de code enrichi ;
- lignes 24-45 : du bouton [Copier] qui permet de mettre du code dans le presse-papiers ;
- lignes 50-55 : des ombres des images ;
- lignes 60-62 : du cadre qui borde la barre supérieure des pages du site ;
config_colors
C’est dans ce fichier que vous contrôlez les couleurs de votre site, principalement la couleur de fond du bandeau supérieur des pages :
COLORS = {
"theme": {
"palette": {
"light": {
"media": "(prefers-color-scheme: light)",
"scheme": "default",
"primary": "teal",
"accent": "purple"
},
"dark": {
"media": "(prefers-color-scheme: dark)",
"scheme": "slate",
"primary": "teal",
"accent": "purple"
}
}
},
"frame": {
# "header_bg_light": "#1E88E5", (bleu)
"header_bg_light": "",
"header_bg_dark": "",
"header_top_border_light": "",
"header_top_border_dark": ""
},
"document_title": {
"color": "#2c3e50"
},
"copy_button": {
"border": "rgba(0,150,136,.45)",
"background": "rgba(0,150,136,.12)",
"text": "rgb(0,150,136)",
"background_hover": "rgba(0,150,136,.20)"
},
"images": {
"shadow": {
"zoomable": "0 8px 24px rgba(0,0,0,.28), 0 18px 60px rgba(0,0,0,.20)",
"zoomable_hover": "0 12px 30px rgba(0,0,0,.32), 0 26px 80px rgba(0,0,0,.22)",
"lightbox": "0 24px 80px rgba(0,0,0,.65)"
}
}
}
Là, il faut être un peu instruit en CSS, ce qui n’est pas mon cas. J’ai utilisé seulement les couleurs des lignes 7 et 13 qui fixent la couleur du bandeau supérieur.
config_files_to_copy
Ce fichier liste les fichiers qui doivent être copiés à la racine du site web généré :
FILES_TO_COPY =[
"google5179c0eaff293e02.html",
"robots.txt",
"word-odt-vers-html-janv-2026.pdf",
"word-odt-vers-html-janv-2026.zip"
]
- lignes 2-3 : sont nécessaires pour le suivi Google du site généré (voir paragraphe 13) ;
- lignes 4-5 : les fichiers que vous voulez copier à la racine de votre site web pour les mettre à disposition de vos visiteurs ;
config
Le fichier [config.py] est le fichier de configuration utilisé par les deux convertisseurs. Il rassemble toutes les informations dont ils ont besoin. C’est un fichier qui normalement ne devrait jamais être modifié. Il est complexe et c’est pourquoi on a décidé d’en extraire les paramètres de configuration susceptibles de changer et de mettre ceux-ci dans des fichiers externes.
from config_urls import URLS
from config_texts import TEXTS
from config_code import CODE
from config_styles import STYLES
from config_colors import COLORS
from config_presentation import PRESENTATION
from config_files_to_copy import FILES_TO_COPY
config = {
"toc": {
"home_label": TEXTS["home_label"]
},
"mkdocs": {
"site_name": TEXTS["site_name"],
"site_url": URLS["site_url"],
"site_description": TEXTS["site_description"],
"site_author": "Serge Tahé",
"repo_url": URLS["repo_url"],
"repo_name": "GitHub",
"use_directory_urls": False,
"theme": {
"name": "material",
"custom_dir": "overrides",
"features": [
"navigation.sections",
"navigation.indexes",
"navigation.expand",
"toc.integrate",
"navigation.top"
],
"palette": [
{
"media": COLORS["theme"]["palette"]["light"]["media"],
"scheme": COLORS["theme"]["palette"]["light"]["scheme"],
"primary": COLORS["theme"]["palette"]["light"]["primary"],
"accent": COLORS["theme"]["palette"]["light"]["accent"],
"toggle": {
"icon": "material/brightness-7",
"name": TEXTS["toggle_to_dark"]
}
},
{
"media": COLORS["theme"]["palette"]["dark"]["media"],
"scheme": COLORS["theme"]["palette"]["dark"]["scheme"],
"primary": COLORS["theme"]["palette"]["dark"]["primary"],
"accent": COLORS["theme"]["palette"]["dark"]["accent"],
"toggle": {
"icon": "material/brightness-4",
"name": TEXTS["toggle_to_light"]
}
}
]
},
"markdown_extensions": [
"admonition",
"attr_list",
"pymdownx.superfences",
"pymdownx.mark",
{
"pymdownx.highlight": {
"anchor_linenums": True,
"linenums": None
}
},
"md_in_html",
"footnotes"
],
"extra_javascript": [
"javascripts/focus.js"
],
"extra_css": [
"stylesheets/focus.css"
]
},
"footer": (
"{% block footer %}\n"
" <div class=\"md-footer-meta md-typeset\">\n"
" <div class=\"md-footer-meta__inner\">\n\n"
" <div>\n"
f" <a href=\"{URLS['author_site']}\" target=\"_blank\">\n"
f" {URLS['author_site']}\n"
" </a>\n"
" <br>\n"
f" {TEXTS['footer_license_sentence']}\n"
" </div>\n\n"
" </div>\n"
" </div>\n"
"{% endblock %}"
),
"extra": {
"analytics": {
"provider": "google",
"property": "G-XXXXXXXX"
}
},
"document_title": {
"style_names": STYLES["style_names"],
"css": (
f"font-size: {PRESENTATION['document_title']['font_size']}; "
f"font-weight: {PRESENTATION['document_title']['font_weight']}; "
f"margin-bottom: {PRESENTATION['document_title']['margin_bottom']}; "
f"line-height: {PRESENTATION['document_title']['line_height']}; "
f"color: {COLORS['document_title']['color']};"
)
},
"code": {
"case_insensitive_languages": ["sql", "html", "vbnet", "vbscript"],
"style_keywords": ["code"],
"default_language": "text",
"rich_line_height": PRESENTATION["code"]["rich_line_height"],
"rich_font_family": PRESENTATION["code"]["rich_font_family"],
"rich_font_size": PRESENTATION["code"]["rich_font_size"],
"detection_rules": CODE["detection_rules"],
"copy_button": True,
"copy_label": TEXTS["copy_label"],
"copy_copied_label": TEXTS["copy_copied_label"],
"copy_only_recognized_language": True,
"copy_min_lines": 4,
"copy_allow_pygments_heuristic": True,
"copy_style": {
"container": PRESENTATION["copy_button"]["container"],
"btn": (
PRESENTATION["copy_button"]["btn"]
+ f"border:1px solid {COLORS['copy_button']['border']}; "
+ f"background:{COLORS['copy_button']['background']}; "
+ f"color:{COLORS['copy_button']['text']}; "
),
"btn_hover": (
f"background:{COLORS['copy_button']['background_hover']}; "
+ PRESENTATION["copy_button"]["btn_hover"]
),
"btn_copied": PRESENTATION["copy_button"]["btn_copied"]
}
},
"images": {
"shadow": {
"enabled": PRESENTATION["images"]["shadow"]["enabled"],
"border_radius": PRESENTATION["images"]["shadow"]["border_radius"],
"zoomable": COLORS["images"]["shadow"]["zoomable"],
"zoomable_hover": COLORS["images"]["shadow"]["zoomable_hover"],
"lightbox": COLORS["images"]["shadow"]["lightbox"],
}
},
"frame": {
"header_bg_light": COLORS["frame"]["header_bg_light"],
"header_bg_dark": COLORS["frame"]["header_bg_dark"],
"header_top_border_light": COLORS["frame"]["header_top_border_light"],
"header_top_border_dark": COLORS["frame"]["header_top_border_dark"],
"header_top_border_width": PRESENTATION["frame"]["header_top_border_width"]
},
"files_to_copy": FILES_TO_COPY,
"debug": True
}
- lignes 1-7 : on importe tous les fichiers de configuration ;
- ligne 9 : le fichier de configuration est un script Python. Il définit une unique variable [config]. Celle-ci est un dictionnaire qui va contenir toutes les valeurs de la configuration ;
- ligne 11 : le libellé du lien « Accueil » ;
- ligne 14 : le dictionnaire [mkdocs] va configurer le fichier [mkdocs.yml] généré par le convertissseur Gemini / ChatGPT. Ce fichier sert ensuite au script [build] pour construire un site HTML à partir du site MkDocs généré par le convertisseur ;
- lignes 15-20 : configurent le site GitHub qui va héberger le site HTML créé à partir du document ODT / DOCX (cf paragraphe 12)
- ligne 21 : cette ligne est importante. Si elle est absente, au lieu d’afficher une page HTML, le navigateur ouvrira le dossier de cette page ;
- ligne 24 : MkDocs propose plusieurs thèmes pour un site MkDocs / HTML. Ici nous avons choisi le thème « material », ligne 24 ;
- lignes 27-31 : configuration de la navigation dans le site. Celle-ci se fera à l’aide d’une table des matières située dans la colonne de gauche de la page affichée (ligne 30) ;
- lignes 33-54 : définissent deux palettes de couleurs : le mode clair (lignes 35-42) ou le mode sombre (lignes 45-52). Une icône dans la barre supérieure des pages affichées permet de passer de l’un à l’autre ;
- lignes 57-70 : des extensions au langage MarkDown utilisé par MkDocs. Ces extensions ont été générées par Gemini à la suite de certaines de mes demandes ;
- ligne 73 : le script [focus.js] est un script Javascript généré par Gemini. Il est associé au bouton de la barre supérieure du site pour afficher ou cacher la table des matières ;
- ligne 76 : le CSS utilisé par ce bouton ;
- lignes 80-95 : la définition du pied de page du site HTML. A été généré par Gemini à partir d’un exemple texte que je lui ai donné ;
- lignes 97-100 : définition du marqueur Google Analytics (GA) qui va permettre de suivre les visites du site ;
- ligne 99 : mettez-là votre marqueur GA ;
- lignes 103-112 : le style du titre du document, celui qui est présent dans le document ODT /DOCX avant le premier titre de niveau 1. Le style indiqué ligne 104 change avec chaque Document ODT. En revanche il peut être constant (‘Titre’) pour les documents DOCX. Par défaut, le convertisseur logue les styles de tous les paragraphes du document ODT / DOCX qui précèdent le premier titre de niveau 1. Il faut donc faire une première exécution, repérer le style du paragraphe qu’on veut mettre en titre, puis mettre dans le fichier [config_styles] ;;
- lignes 105-111 : le style CSS que vous voulez donner au titre du document. Ce titre est dans la page « Accueil », la première page affichée lorsque le site s’ouvre ;
- ligne 115 : vous mettez là les langages insensibles à la casse (majuscules / minuscules) ;
- ligne 116 : les blocs de code sont repérés par leurs styles dans le document ODT / DOCX. Il peut y en avoir plusieurs. Ligne 116, on met tous les mots clés qui permettent de détecter un style de code. Dans mes documents, tous mes styles de code ont le mot « code » dans leur nom. Et aucun autre style n’a ce mot dans son nom. Donc je peux me contenter de mettre un unique mot clé. S’il y en a plusieurs on les met en les séparant par des virgules ligne 116 ;
- ligne 117 : fixe le langage par défaut. Dans le cas d’un bloc de code « plain text », si aucun langage n’est détecté, le langage par défaut sera « text ». Pour MkDocs, cela signifie un bloc de code sans coloration syntaxique. C’est par exemple, le cas de résultats d’exécution ;
- ligne 121 : cette configuration est utilisée pour les codes en « plain text » qui n’ont pas initialement de coloration syntaxique. Ces lignes visent à leur en donner une selon le langage utilisé dans le bloc de code. Il est à noter que si vos codes sont tous enrichis car provenant d’un IDE tels Eclipse, Visual Studio, ... et que vous n’avez pas de bloc de code « plain text » associé à un langage, alors vous n’avez rien à mettre dans cette partie de la configuration. Vous pouvez laisser vides les tableaux associés aux langages. Tout cela se passe dans le fichier de configuration du code [config_code] ;
- lignes 118-120 : ces lignes concernent les blocs de code enrichis (gras, italique, soukignage, surlignage, couleur des caractères). Ces blocs ne subissent pas le traitement des blocs de code « plain text ». Ils sont rendus à l’identique dans le HTML ;
- ligne 118 : fixe la hauteur de ligne des lignes de code ;
- ligne 119 : fixe la police CSS du bloc de code ;
- ligne 120 : fixe la taille des caractères ;
- lignes 144-152 : fixent l’apparence des images ;
- lignes 154-160 : fixent l’apparence du cadre dans lequel est affiché la page web ;
- ligne 162 : la liste des fichiers à copier à la racine du site HTML ;
- ligne 164 : [debug] à True autorise les logs des styles des paragraphes qui précèdent le premier titre de niveau 1 du Document ODT / DOCX. Ce sont dans ces logs qu’on trouvera le style exact du paragraphe devant servir de titre dans la page d’accueil du site ;
Au final, lorsqu’on passe d’un Document ODT / DOCX à l’autre, on ne changera rien au fichier [config.py]. On ne modifiera que les autres fichiers de configuration.