When crafting documentation using the Docs-as-code approach, authors often use plain-text formats such as Markdown.
One popular tool for rendering Markdown is MkDocs, a static site generator for project documentation.
With MkDocs you can easily host your site on platforms like Netlify, GitHub Pages, GitLab Pages, just to mention but a few.
In this article, we will focus on Material for MkDocs a powerful documentation framework built on top of MkDocs.
We will go through the setup process with installations done using pip, the Python package manager and Docker.
Before we get started here are some few things you will need:
Prerequisites
You need to have:
- Installed a recent version of Python
- Installed Python package manager, pip
Note that if you are not familiar with Python, you can still install Material for MkDocs with Docker.
Project Setup
We will begin our project setup using pip. If you plan on using Docker you can skip to the section below.
Installation with Pip
Material for MkDocs is published as a Python package. Therefore, you can install it with pip, ideally using a virtual environment.
Let's begin by setting up a virtual environment.
Create a Virtual Environment
Initializing a virtual environment is important especially if you want to keep the dependencies of different projects separate.
With a virtual environment, you can create an isolated Python interpreter for your project. This way, it's easy to avoid potential issues caused by updating libraries used by your system tools.
Additionally, with a virtual environment, your teams can work in the same environment thus maintaining consistency across development and deployment.
To create a new virtual environment, open your terminal and navigate to your project directory.
Use the built in venv module to set up a Python virtual environment called venv.
To do so, run the following code:
python -m venv venv
Next, activate your virtual environment by running:
source venv/bin/activate
Now you can install MkDocs material using pip with the following command:
pip install mkdocs-material
The above command lets you automatically install all dependencies including:
- MkDocs
- Markdown
- Pygments
- Python Markdown Extensions
Installation with Docker
Opting for Docker for Material for MkDocs installation means that all dependencies come pre-installed.
You get the following plugins bundled with the Docker image:
Use the Docker image to get started. Pull the image with:
docker pull squidfunk/mkdocs-material
However, note that the docker container is not suitable for deployment but for previewing purposes only.
Setting Up Your Site
Now you can use the mkdocs executable to bootstrap your project documentation.
Proceed to open your project folder in VS Code. Before anything, make sure you have activated your virtual environment.
Now open the terminal within VS Code and run:
mkdocs new .
If you are running MkDocs from within Docker, use:
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
You will create a folder structure like the one illustrated below:
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
Now, to startup your new website run:
mkdocs serve
This is how your site should look like:
Configuration
Since the MkDocs site looks a little bland, the next step is to setup Material theme for an even better look.
Material Theme
In order to load material theme on your docs site, go to the mkdocs.yml file and set the following configurations and save the changes.
The result is a more cleaner and proffessional-looking static site.
Conclusion
In this article, we have covered the steps needed to setup an MkDocs site with the Material Design theme. Now you can create more seamless documentation for your commercial or open source projects.
Follow me on Twitter and Medium for more tutorials and guides.
Keep building! 🌟
Top comments (0)