MkDocs and GitHub Pages
This website was created using MkDocs
, surrounding python packages like mkdocs-material, and is served with GitHub pages.
About MkDocs and its plugins
The MkDocs library makes it easy to create documentation from just markdown and YAML files.
With just a few commands, you can quickly iterate with your content and make some great looking webpages.
There is also a handful plugin libraries for MkDocs that allow for additional customization. For instance, the theme used here is from the mkdocs-material
package. Makes it so easy to have a good looking site on all platforms (especially for people like me who don't make user interfaces often ).
Creating the Content and Theme
MkDocs really makes it so easy to set up a page. The Getting Started Section allows you to get started.
The simpliest project setup will just be two files:
The themes and capabilities were inspired from the mkdocs-material site and exploring its mkdocs.yml helped implement mine.
Serving with GitHub Pages
GitHub allows you to set up a site for free. If the repo is named <username>.github.io
, then it will be hosted at https://<username>.github.io
.
Tip
If you deploy with GitHub pages in any other repo, the docs with be hosted at https://<username>.github.io/<repo-name>
. Super cool and would like to use in the future to make quick project documentation!
All the code to create this site is on my GitHub here.
GitHub Action
The mkdocs-material documentation has the steps in order to set up your GitHub Action for deploy. Those steps are found here.
GitHub Page Settings
I had some hiccups while setting up the site. Initially, only my README was being served at https://wd60622.github.io. However, the default "Deploy from a branch" setting in the GitHub Pages section was on the main
branch which only had the README.
Note
Running mkdocs gh-deploy
pushes all the html files to gh-pages
branch in my repo so that branch needed to be selected in the Settings.
Below are Settings section that worked for my deployment.
Helpful Links
I found these links helpful while setting up this site and writing this post.