Publish your Markdown docs on GitHub Pages

As a developer you've most likely switched machines, even OS several times. Maybe you've performed a specific set of operations that you'll have to repeat in the future? want to remember some command lines? share code snippets? capture online course notes? 

For all of the reasons above, and many more, having a personal documentation website is ideal. It lets you organize and synthesize all the information that is relevant to YOU in your own personal way, with the added benefit of being easily shareable. 

What we'll do

A project containing all your Markdown files, hosted on Github Pages.

Requirements

• Python 3 (tested with version 3.9.5+)
• Git (2.12+)
• Make 

How we do it

Install mkdocs

We'll use mkdocs as static site generator, so let's install it:

pip install mkdocs

Create your docs source project

Now create the basic project structure, in your projects folder:

mkdocs new GITHUB_USERNAME
cd GITHUB_USERNAME

Replace GITHUB_USERNAME with your GitHub username or whatever you prefer to name your project. We'll be referencing it in the next steps and it will become clearer why you might want to choose that project name. 

Check the created files in that folder, you'll see something like the following:

./
-- docs/
-- mkdocs.yml

Go ahead and try running mkdocs serve then open http://127.0.0.1:8000 in your browser. And voilà! You have a personal documentation local website. Any .md file added in docs/ will appear as a new web page. Try to edit docs/index.md for example.

mkdocs.yml contains your project configuration. You can customize your site name, navigation layout and so on. A simple example would be:

site_name: your site name
site_url: https://GITHUB_USERNAME.github.io
site_author: you
site_description: a short description of your website

nav:
  - About: index.md

You can also use the readthedocs provided theme by adding the following:

theme:
  name: readthedocs
  highlightjs: true
  hljs_languages:
    - yaml

For reference see https://www.mkdocs.org/user-guide/configuration/

At this point you should have something like this locally:

For a local documentation project that would be enough. But we'll go ahead and make this deployable to your GitHub page.

Create the GitHub repositories

GitHub allows you to host a website in a specific repository matching GITHUB_USERNAME.github.io, with your actual GitHub username in place of GITHUB_USERNAME.

Luckily mkdocs makes it easy to push your project build files to your GitHub page through the mkdocs gh-deploy command.

The downside of mkdocs gh-deploy is that it wipes out all the files in GITHUB_USERNAME.github.io/ to generate the website files (html, css, js).

To overcome this constraint and simplify the deploy process you'll track your GitHub page repo, GITHUB_USERNAME.github.io, independently as a git submodule of your docs source project. Which will allow to run mkdocs gh-deploy from within the docs source project itself.

Ultimately you'll need two distinct repositories: one for your GitHub page, another one for your source files.

Create the GitHub page repo

• Go to https://github.com/new and create your GitHub page repository
• Name it GITHUB_USERNAME.github.io (replace GITHUB_USERNAME with your actual GitHub username)

📝 Edit 16 Apr 2023
If you did not choose your GitHub username in lieu of GITHUB_USERNAME then you might have to do a couple of extra steps:

• From the github.io repo, choose Settings
• Under Code and automation, click on Pages
• In Source > Deploy from a branch
• In Branch > choose main and save
• Type in the URL of your website "my-new-docs-website.github.io" and save

Thanks for the feedback @konsoul!

Create the source repo

• Go to https://github.com/new and create your source repository
• Name it GITHUB_USERNAME (replace GITHUB_USERNAME with your actual GitHub username or anything else you chose to name the new mkdocs project previously created)

📝 A repository named as your username is a special repository on GitHub. Its README.md will appear on your public profile. So you can customize that as well.

At this point you should have two GitHub repositories:

Git repo	Description
GITHUB_USERNAME.git (or anything else you chose to name it)	Source repo with markdown files
GITHUB_USERNAME.github.io.git	GitHub page repo with static web files

Initialize the git repositories

Back in the folder created previously:

git init

echo site/ > .gitignore

git add .
git commit -m "first commit"

git branch -M main
git remote add origin SOURCE_REPO # replace SOURCE_REPO with your source repo HTTPS or SSH adddress
git push -u origin main

Then initialize the GitHub page repo:

# still in your source folder

mkdir GITHUB_USERNAME.github.io
cd GITHUB_USERNAME.github.io

git init
git commit --allow-empty -m "first commit"

git branch -M main
git remote add origin GH_PAGE_REPO # replace GH_PAGE_REPO with your source repo HTTPS or SSH adddress
git push -u origin main

cd ..

You should now have two folders tracked in their respective GitHub repositories:

GITHUB_USERNAME/                  Source repo
-- GITHUB_USERNAME.github.io/     GitHub page repo
-- docs/
-- .gitignore
-- mkdocs.yml

Now delete GITHUB_USERNAME.github.io/ since there's no need for it to exist independently:

rm -rvf ./GITHUB_USERNAME.github.io

Add your GitHub page repo as a submodule of your source repo instead:

git submodule add -b main GH_PAGE_REPO # replace GH_PAGE_REPO with your source repo HTTPS or SSH adddress
git add GITHUB_USERNAME.github.io
git commit -m "add github page submodule"
git push

Deploy your docs to your GitHub page

Run:

cd GITHUB_USERNAME.github.io
mkdocs gh-deploy --config-file ../mkdocs.yml --remote-branch main
cd ..

Go ahead and open https://GITHUB_USERNAME.github.io in your browser. And voilà! Your very own personal documentation on your GitHub page.

📝 You might have to wait a few seconds for your changes to be deployed.

Add deploy command in Makefile

The mkdocs gh-deploy command in itself isn't very user friendly nor easy to remember so we'll add a simple Makefile to make (word choice on purpose) it easier to deploy changes.

Create a Makefile in your source folder with the following:

SHELL := /bin/bash
GH_PAGE := GITHUB_USERNAME.github.io

.PHONY: deploy
deploy:
    cd $(GH_PAGE) && mkdocs gh-deploy --config-file ../mkdocs.yml --remote-branch main

📝 Ensure to paste Makefile indentation as Tabs or else you might get an error in the lines of [...] *** missing separator. Stop.

Now you can simply run make deploy whenever you want to publish something.

Keep both repositories in sync

You might also want to update latest commit version of your GitHub page submodule whenever a deploy is performed. Not technically required, but good for tracking purposes. Add the following in your Makefile:

.PHONY: update-build-version
update-build-version:
    git submodule update --remote --merge
    git add $(GH_PAGE)
    git commit -m "ci: update build version"

.PHONY: publish
publish: deploy update-build-version
    git push

make publish will handle the deploy and update your submodule version.

A typical workflow would be:

1. make some changes to your markdown files or mkdocs.yml
2. git commit -am "commit message"
3. git push to your source repo
4. make publish to your GitHub page

Why so complicated ?

Can't I just run mkdocs build and use site/ as my GitHub page?
You can! See the GitHub docs. You will need to commit the build site/ artifacts, or you could even use a different branch for the GitHub page altogether. IMHO I'd much rather track the actual source code and deploy the minimal amount of files in the public project, and having two completely unrelated branches in the same repository is kind of an overly obscure solution. Hence the submodule approach. But that is my biased opinion, use whichever solution works best for you!

Just show me the code

Here is a sample project containing the output of everything described in this post:

• https://github.com/ar2pi/sample-mkdocs-gh-project

Similar articles

Here are a few other articles I could find before writing this post:

• Create your own mkdocs with Github pages (by cosckoya)
• Custom GH Pages deploys made easy (by Michael)
• MkDocs : Static HTML sites and documentation preparation tool that you can host on GitHub pages (by Sandeep Balachandran)

Summary

You just created a brand new GitHub page hosting all your desired markdown generated documentation. Which can also contain your cv, portfolio, todo list, random thoughts, cat pictures, etc. you name it. Go nuts, the web is limitless.

Happy hacking!

Comments

[Brad Rappa]

Just to note. I had to do a couple extra steps, possibly something I did wrong, or maybe GitHub updated something:

1. Under the github.io repo, choose Settings.
2. In the "Code and automation" section of the sidebar, click Pages
3. In "Source" choose "Deploy from a branch".
4. Below choose "main".
5. Type in the URL of your website "my-new-docs-website.github.io".
6. Click Save.

Website is now live. I hope this helps someone! Thank you for the article this will be great to have my own repo of documentation!

[Arthur Picerna]

That would be because the Github Page name doesn't match your Github username, in which case the settings are not set automatically.

I updated the article to reflect that use case as well.

Thanks for the feedback!

[Bijan John]

This article saved me lots of hassle as I was getting hung up on "The downside of mkdocs gh-deploy is that it wipes out all the files in GITHUB_USERNAME.github.io/ to generate the website files (html, css, js)." I wish mkdocs would have made this more clear, great write up!