Troubleshooting Deploying Documentation Using MkDocs
Recently, I was developing a package for my job. One of the requirements was to make
sure that it was properly documented. Being a big fan of Markdown, MkDocs
was a natural choice. Not only is it easy to pick up and customize, but Material for MkDocs
offers some fantastic functionality on top of it. With very little effort, you can add admonitions
(the nice colorful boxes with handy information), tables ,
site search , and many others.
After spending time and effort in writing the documentation per se, it was finally time to go live and deploy it. You can do this manually using GitHub Pages. However, in my case it was much handier to automate the documentation deployment after every push. GitHub Actions allow you to do this very easily. Unfortunately, this solution didn’t really work out of the box for me. In this post, I will share the problems I ran into and how I fixed them. Maybe this will be useful for someone else.