From Gitbook to Mkdocs
This post will serve as a reminder for motivation and example for moving from Gitbook to Mkdocs for Github Pages-hosted and Github Actions-built cheatsheet document publication.
Motivation ¶
As of early 2020, I had converted a git blog post from a post to a “cheatsheet” website using Gitbook. That blog post can be found here.
However, when I went to add to a new “cheatsheet” in late 2021 I found that the CI/CD for Gitbook was failing.
Given that I’m writing this retrospective many months after-the-fact, I cannot recall the exact errors I was encountering. The long-and-the-short of it was that Gitbook was not supported in the opensource capacity that it once was and I needed to replace my usage of it with something else.
Alternatives ¶
When moving away from Gitbook, my requirements were:
- input multiple files
- input files in markdown
- generate static web content (and serve with Github Pages)
- easy to build artifacts via Github Actions
I entertained a few options:
- Pandoc
- LaTeX
- Sphinx
- Mkdocs
Mkdocs ¶
Ultimately, I went with Mkdocs. Mostly because their documentation was very straight forward to get started. In a matter of 15 minutes, I had a basic replacement of my “cheatsheet” website running locally. An hour later, my entire project and CI/CD had been replaced and I washed my hands of the aforementioned Gitbook errors.
I won’t go into details how I implemented Mkdocs here, or how exactly I migrated from Gitbook to Mkdocs. However, I will link to the Pull Request I submitted (to myself) to show the file changeset.