Publication of documents used in the gh-pages branch and organization of comparative knowledge

I will summarize what I learned most about the mechanism for publishing documents using the gh-pages branch of GitHub Pages.

This article summarizes the following aspects:

• How GitHub Pages works

• Basic commands and settings for gh-pages operation

• mkdocs automation support (gh-deploy)

• Cooperation method with sphinx (ghp-import)

• Comparison with Netlify

Relationship between GitHub Pages and the gh-pages branch

GitHub Pages is a mechanism that prepares branches (usually gh-pages) containing static HTML files in a GitHub repository and publishes them on the web.

Published with a URL like this:

https://<ユーザー名>.github.io/<リポジトリ名>/

Also, if you want to use your own domain, you can do so by including the CNAME file in the branch.

—

Examples of Git commands required for gh-pages operation

To manually reflect _build/html and site/ generated by Sphinx or MkDocs to the gh-pages branch, perform the following Git operations.

git checkout --orphan gh-pages
git rm -rf .
cp -r _build/html/* .
touch .nojekyll
echo "example.com" > CNAME
git add .
git commit -m "Publish docs"
git push origin gh-pages

• Create a new branch with no history with --orphan

• Disable Jekyll processing with .nojekyll

• You can specify your own domain using CNAME

—

mkdocs gh-deploy automatic processing

With MkDocs, you can automate the above series of processes simply by using the following commands:

mkdocs gh-deploy

Inside this command:

• Generate HTML with mkdocs build

• Place the contents of site/ into gh-pages via a temporary branch

• CNAME file is also automatically copied (if it exists in the root)

It is very concise and easy to operate even for beginners.

In Sphinx, it is standard to use ghp-import.

Since Sphinx does not have gh-pages support by default, it is common to use the ghp-import package as shown below.

pip install ghp-import
make html
ghp-import -n -p -f _build/html

• -n: Add .nojekyll

• -p: push automatically

• -f: Force overwrite

It is often incorporated into CI/CD and linked with GitHub Actions, etc.

—

Comparison with Netlify

Netlify is also strong in hosting static sites and has the following features:

item	GitHub Pages (gh-pages)	Netlify
build automation	Manual construction using GitHub Actions, etc.	Easy to configure with GUI
PR preview	✖(No standard features)	✔ Automatically generate Preview URL
custom domain	Compatible with CNAME (SSL is provided by ourselves)	Automatic SSL support and DNS management possible
dynamic capabilities	✖ Static HTML only	✔ Forms / Functions etc.

—

summary

• By understanding the gh-pages branch, you can operate a lightweight static site.

• With Sphinx/MkDocs, full automation is possible by incorporating the flow of HTML output → gh-pages reflection into CI/CD.

• Compared to Netlify, it stands out for its high level of convenience, including PR preview and automatic SSL management

• On the other hand, the lightweight nature of GitHub Pages and the ease of understanding GitHub integrated operation are also major attractions.

Going forward, I want to choose between these options by weighing the effort required for automation against the richness of the hosting features, depending on my own use case and team structure.

Article information

author:

Mr. Takagi

Post date:

2025-05-25

Basics of the Python task automation tool “doit”   Measurement method for Sphinx build time (time command and Measure-Command)