Migrating Blog from Jekyll to MkDocs on GitHub Pages¶
Introduction¶
This article will describe the steps to migrate a blog from Jekyll to MkDocs on GitHub Pages.
For a while, I've been looking for better ways to organize my blog. Recently, I came across MkDocs (Material Theme), and it seemed promising. Jekyll has many different themes, and there may be a theme out there that works much better than MkDocs, but I haven't find it yet. I know it's out there!
My objective for this project was to organize my blog better while spending the least amount of time. MkDocs (with Material Theme) seems to offer these out of the box. If you know of other frameworks/themes that better meet this objective, please let me know.
Here is how the old blog looked:
Here is how the new blog looks:
The Basics¶
I am not going to go into the details of installing and configuring MkDocs. The MkDocs Documentation is good at providing this information. Please refer to this documentation for installation and configuration.
After you install and configure MkDocs. Create the mkdocs.yml for your blog. This file includes things like the theme and menus. Here is a copy of this website's mkdocs.yml for reference.
Make a copy and update the blog from Jekyll to MkDocs folder. I had to make some minor changes to the Jekyll posts. For example, I had to remove the Jekyll headers in the blog posts and verify all the image links work correctly.
At this point, you have a working MkDocs blog, and now you're ready to deploy it to GitHub Pages.
GitHub Pages Deployment¶
To deploy your blog with MkDocs on GitHub, you need two folders. You need a project folder (which includes the actual blog) and a folder for the GitHub repository.
To better understand how MkDocs deployment works, read this. In summary, this is how the two folders may look like:
my-project/
mkdocs.yml
docs/
orgname.github.io/
The my-project/docs/ contain the markdown code for the blog. The folder orgname.github.io is your GitHub Pages repository. Where orgname is the username is your username (or organization name) in GitHub.
The statically generated website is deployed to GitHub with the following code:
cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
I wanted to deploy the new website in a way that I could revert to the old blog. To do this, I decided to create a new branch (main) for my existing GitHub Pages repository. I had to run the following commands to complete this:
mkdir Mo4n6.github.io
git init
git remote add origin https://github.com/Mo4n6/Mo4n6.github.io
git checkout -b main
echo "Website" > Readme.md
git add Readme.md
git commit -m 'main branch'
git push origin main
The git checkout -b main will create the new branch main.
To create the static website with MkDocs and to deploy it to GitHub, I ran the following command:
cd ../Mo4n6.github.io/
mkdocs gh-deploy --config-file ../website/mkdocs.yml --remote-branch main
where,
website- is your blog folder (with the Markdown code).main- is the name of the branch you want to push to.orgname- is the username is your username (or organization name).
Warning
From MkDocs:
You should never edit files in your pages repository (eg. Mo4n6.github.io folder) by hand if you're using the gh-deploy command because you will lose your work the next time you run the command.
Now, you've deployed your blog to a new branch on GitHub. You're ready to update the GitHub Pages setting to serve the new blog.
Custom Domains¶
As per docs, in addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a CNAME file to the root of your docs_dir. In my case, I had to run the following command in the root website folder:
cd docs
echo "www.sharif.org" > CNAME
The Switch Over¶
This section will go over switching GitHub Pages from the old branch to the new.
To do this, update the branch under "Settings>Options>GitHub Pages" to point to the new branch. In my case, I had to open the repository Mo4n6.github.io and go to Settings>Options. I had to select the "main" branch under "GitHub Pages". Here is a screenshot:
Summary¶
The migration went as expected. In the future, I may look at adding Google Analytics to the blog. I learned about MkDocs and GitHub pages. I am grateful for markdown as it made easy work migrating the posts from Jekyll to MkDocs.
Overall, this was a fun project that I enjoyed doing. I look forward to using the new blog.