Beginners Guide for MkDocs and how to deploy

What is MkDocs?

MkDocs is a fast, simple, and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

What is the Material for MkDocs?

Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you’re familiar with Python, you can install Material for MkDocs with pip, the Python package manager.

How to Setup?

First things first install the python library

pip install mkdocs-material

with docker

docker pull squidfunk/mkdocs-material

with git

git clone https://github.com/squidfunk/mkdocs-material.git

Now after successfully installing the packages, we should create a empty directory for the project like

mkdocs new .

This creates a new mkdocs files in which we can write the static pages

We have to do few configurations in order to use material of mkdocs for that

#mkdocs.yml
theme:
  name: material

Preview as your writing, use this command in the terminal

mkdocs serve 

Point your browser to localhost:8000 and you should see:

After the final draft we have to build the mkdocs project

mkdocs build

Finally, Deploy 🙂

You can freely public your page in github pages or gitlab pages

With Github:

• First, push your code to a new repository.
• Go to the settings of that particular repository.
• scroll down until you see Github pages.
• click on it and select the beach, mostly that would be main or master branch.
• Choose a theme if you want to and click next
• Within few minutes you static pages gets deployed.

You can do a lot of customization in the mkdocs such as colors,font, languages, themes, logos and icons and much more

Check out their official page for more information