Skip to content

12. Hosting the HTML site on GitHub

It was Gemini himself who suggested that I host the HTML site generated by his two scripts on GitHub1 . I didn’t know that was possible. GitHub is a site that hosts development projects. Uploading programming courses there seems like a natural fit.

First, you need to have a GitHub account. If necessary, create one.

Log in to your GitHub account:

  • In [2], your existing repositories, if you have any;
  • In [3], create a new GitHub repository;
  • In [1], use the name you entered in [config.py]: 

  "repo_url": "https://github.com/stahe/word-odt-vers-html-janv-2026",
  • In [2], you can also enter the same information as in [config.py]: 
1
  "site_description": "Convert a Word or ODT document into a static HTML site using Gemini 3 and ChatGPT 5.2 AI,"
  • In [3], confirm the creation of your GitHub repository;

It is recommended that you create a [README.md] file for each GitHub repository, which will be displayed in place of the screen above. It must be written in Markdown, which isn’t exactly straightforward. So we’ll write a text file containing what we’d like to see in the README. Then we’ll ask the AI to generate the corresponding README.md file.

The text file [readme.txt] will be as follows:

1
2
3
4
5
6
7
In this article, we aim to provide readers with a Python converter for converting Word or ODT documents into a static HTML site.

This converter was built by the Gemini 3 AI.

When the ODT document is suitable, the converter generates an HTML site via MkDocs that has the professional look of sites produced by Pandoc.

I used Gemini 3 with a Pro subscription.

The prompt for Gemini is as follows:

  • In [1], the attached file [readme.txt];
  • In [2], the prompt;

Copy the response Gemini gives you into the [README.md] file in your working folder. Here is the response Gemini gave me:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# Word/ODT to HTML Site Converter (MkDocs)

🔗 **[View the generated demo site](https://stahe.github.io/word-odt-vers-html-janv-2026/)**

---

## 📝 Description

This project aims to provide readers with a Python converter for converting Word or ODT documents into a static HTML website.

When the ODT document is suitable, the converter generates an HTML site using **MkDocs** that has the professional look of sites produced by Pandoc.

## 🤖 Development Background

This converter was built entirely by the **Gemini 3** AI (with a pro subscription). It is the result of successive iterations to finely manage the structure of ODT (OpenDocument Text) documents.

## ✨ Features

The `convert.py` script performs the following actions:

* **ODT to Markdown Conversion**: Parses the `.odt` (XML) file to extract its structure.
* **Heading Management**: Automatically generates the Table of Contents (TOC) and sidebar navigation.
* **Code Blocks**: Automatic language detection, syntax highlighting, and **precise line numbering** (`start-value` attributes).
* **Lists**: Support for bulleted and numbered lists with correct indentation.
* **Formatting**: Support for *bold*, *italic*, *underline*, and *highlighting* (preserving original colors).
* **Images**: Automatic extraction and embedding of images contained in the document.
* **Configuration**: Customization via a `config.py` file (Footer, Google Analytics, etc.).

## 🚀 Installation

### Prerequisites

* Python 3.x
* The following libraries:

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

```

### Project Structure

Make sure you have the following files:

* `convert.py`: The conversion script.
* `config.py`: Your configuration file.
* `your-document.odt`: The source document.

## 💻 Usage

1. **Conversion**
Run the script by specifying the source ODT file and the configuration file:
```bash
python convert.py your-document.odt config.py

```


*This will generate a `docs/` folder containing the Markdown files and an `mkdocs.yml` file.*
2. **Preview**
To view the site locally:
```bash
mkdocs serve

```


3. **Generation**
To build the static site (folder `site/`):
```bash
mkdocs build

```



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

The `config.py` file lets you control the site's appearance:

* **mkdocs**: General site settings (title, description, Material theme).
* **footer**: Complete HTML code for customizing the footer.
* **code**: Language detection rules for syntax highlighting.
* **extra**: Google Analytics (GA4) configuration.

## 📄 License

This tutorial written by **Serge Tahé** is made available to the public under the terms of the:
*Creative Commons Attribution – Non-Commercial – ShareAlike 3.0 Unported License.*

He provided me with a very comprehensive README. That’s because Gemini is very familiar with this project, which we’ve been working on for weeks. You’ll likely have a less detailed [README.md].

Now let’s return to our working directory:

  • In [2], the README file you just modified;
  • In [1], the [deploy.txt] file explains how to export your HTML site to your GitHub repository;

The contents of the [deploy.txt] file are as follows:

1
2
3
4
5
6
7
8
9
git init
git branch -M main
# Check .gitignore first!
git add .
# first commit
git commit -m "Initial commit: MkDocs source"
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

This sequence of commands will export your HTML site to your GitHub repository. You will need to modify line 7 with the URL of your own GitHub repository, found in the [config.py] file:

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

You should also check another URL in the [robots.txt] file:

The contents of the [robots.txt] file are as follows:

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

On line 3, enter your site’s URL, the same one used in the [config.py] file:


        # Site publication URL (e.g., GitHub Pages)
        "site_url": "https://stahe.github.io/word-odt-vers-html-janv-2026/",

The [robots.txt] file is not used during local site build, but it will be used when the site is hosted on GitHub.

The command sequence in [deploy.txt] uses a program called Git. You must install it [Git - Install for Windows].

Once that’s done, check the file named [.gitignore] in your working directory. It tells Git which files to ignore. My [.gitignore] file is as follows:

1
2
3
4
5
# 1. Ignore ALL project files and folders
*

# 3. We make an exception (!) for the single file you want to keep
!README.md

It’s extremely simple. We ignore all files (line 2) except the [README.md] file (line 5). GitHub is designed to host development projects. Typically, the entire development project is uploaded to GitHub. We’re simply looking to upload an HTML site, not a development project. The only file we want to export to our GitHub repository is the [README.md] file, which explains to visitors what our HTML site contains.

Now, in your terminal, type the following sequence of commands in the order specified by [deploy.txt], up to command 8. Do not run command 9 for now.


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-to-html\v2> git branch -M main
PS C:\Data\st-2025\GitHub Pages\word-odt-to-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-to-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-to-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)
Tohttps://github.com/stahe/word-odt-vers-html-janv-2026.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Ctrl-click on the URL in line 17. This will take you to your GitHub repository:

  • In [1], the URL of your GitHub repository;
  • In [2], the new README.md;

Now let’s move on to line 9 of the [deploy.txt] file. This is the command that exports the HTML site to 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    -  The 'les-exemples.md' file 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 the '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: 
Tohttps://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-click on the URL in line 21. This will take you to your new HTML site on GitHub:

  • In [1], you can see that you are displaying a website on GitHub;

It is extremely easy to make a mistake when running the commands in [deploy.txt]. It is then difficult to undo the changes because Git keeps a record of what you’ve done (wrong). To start over, view the working directory:

  • In [1], delete the [.git] folder;

Then go back to PyCharm and run the series of commands from [deploy.txt] again.

What should you do if you modify your ODT/DOCX document? Do the following 3 things:

  1. Convert your ODT/DOCX document again using [convert];
  2. build the HTML site with [build];
  3. export the HTML site to GitHub using the command [python -m mkdocs gh-deploy]. This command is sufficient as long as you do not modify the [README.md] file. If you modify the [README.md] file, you will need to run a few more commands: 
1
2
3
4
5
git add README.md
# commit
git commit -m "README update"
git push -u origin main
python -m mkdocs gh-deploy

If you’ve only modified the README, only commands 1, 3, and 4 are necessary. Command 5 is unnecessary if you’ve already deployed the HTML site and it hasn’t changed since then.

What if you want to start from scratch because things have gone haywire? You can delete your GitHub repository and repeat all the steps in the chapter12 . The option to delete a GitHub repository is well hidden:

  • In [1], go to the repository settings;

Scroll all the way to the bottom of the [settings] page. There you’ll find the button to delete your repository [2].

  1. Footnote for GitHub ↩

https://tahe.developpez.com
This tutorial written by Serge Tahé is made available to the public under the terms of the Creative Commons Attribution – Non-Commercial – ShareAlike 3.0 Unported.