Create your own mkdocs with Github pages

Here is the beginning of a series of posts that will explain how to create your own documentation project with mkdocs. For those who doesnt know what is mkdocs. Mkdocs is a static site generator (SSG) developed in Python that allows anyone to create websites fast; source files are written in Markdown and the configuration is managed by YAML files.

First of all we need to start our mkdocs project is install Python and configure Pip.

Install mkdocs with Pip:

python -m pip install mkdocs --user

Check that mkdocs was correctly installed:

$ mkdocs --version

mkdocs, version 1.1.2 from /home/cosckoya/.local/lib/python3.8/site-packages/mkdocs (Python 3.8)

It's party time! By now mkdocs is already installed and we can create a new project with the following command:

mkdocs new my-mkdocs-project
cd my-mkdocs-project

By now you can build and check a base template project, to do that just run:

mkdocs build --clean
mkdocs serve

This commands would show the following message:

Serving on http://127.0.0.1:8000

And opening that URL will see your mkdocs project running :)

But, what happens if you want to create an online mkdocs project? You could use a lot of different static website providers like AWS S3, Google Firebase, Azure Static Website ... lot of options, the fast one for me is to publish it on a Github pages site.

To do that, we must create a new github repository like mine: https://github.com/cosckoya/wiki. In the "main" branch we will maintain the mkdocs project and in the "gh-pages" branch will be the static content of the mkdocs, this will be generated with the "mkdocs build" command.

We must initialize a repository with the base project folder:

Here is the thing. We can develop our mkdocs project: add some templates, web content, addons or images. After check that the site has everything and after some "build & serve"; we could deploy the site running:

mkdocs gh-deploy

Then navigate to your github pages site. Mine is this:

· https://cosckoya.github.io/wiki

And that's it. Enjoy!

Reference:
· https://www.mkdocs.org
· https://pages.github.com