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.
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:
Then navigate to your github pages site. Mine is this:
And that's it. Enjoy!